                                    ozmake

   [1]Denys Duchier

   provides
          ozmake
     _________________________________________________________________

   see [2]CHANGES for a list of changes between successive versions of
   ozmake.

USAGE

   ozmake OPTIONS TARGETS

   ozmake is a tool for building Mozart-based projects and for creating
   and installing Mozart packages. It was inspired by the Unix tools make
   and rpm, but is much, much simpler, is specialized for Mozart-based
   software development and deployment, and transparently supports all
   platforms on which Mozart has been ported. ozmake must currently be
   invoked from a shell, but it will eventually acquire additionally an
   optional, user-friendly graphical interface.

SYNOPSIS

   ozmake --help
   ozmake [--build] [TARGETS...]
   ozmake --install [TARGETS...]
   ozmake --install [--package=PKG]
   ozmake --uninstall [--package=PKG]
   ozmake --clean
   ozmake --veryclean
   ozmake --create [--package=FILE]
   ozmake --publish
   ozmake --extract [--package=PKG]
   ozmake --list [--package=MOGUL]
   ozmake --config=(put|delete|list) ...
   ozmake --mogul=(put|delete|list|export) ...

OPTIONS

   In the following, we write meta variables between angle brackets, e.g.
   <PREFIX> or <URI as cache path>

  General Options

   -v, --verbose
          print out more tracing information that the default. By
          supplying this option twice, you will sometimes get even more
          information.

   -q, --quiet
          suppress all tracing and feedback information

   -n, --just-print
          perform a dry run, i.e. just print what would happen without
          actually performing the actions

   --local
          do not recurse into subdirectories

   --(no)autodepend
          default: true
          automatically determine build-time and install-time (run-time)
          dependencies. Currently, this is only supported for Oz sources
          by looking at import and require sections.

   --(no)requires
          default: true
          automatically fetch and install other packages that the current
          one requires. This option is relevant both for building and for
          installing.

   What you should remember here, is that -vn is your friend. Add -vn at
   the end of any ozmake invocation, and it will tell you in great detail
   what the command would do, without actually doing it.

  Directories and URLs

   --prefix=<PREFIX>
          default: ~/.oz
          root of private installation area

   --dir=<DIR>
          default: current directory
          default directory for other options below

   --builddir=<BUILDDIR>
          default: <DIR>
          directory in which to build

   --srcdir=<SRCDIR>
          default: <DIR>
          directory where source files are located

   --bindir=<BINDIR>
          default: <PREFIX>/bin
          directory where bin targets are placed

   --libroot=<LIBROOT>
          default: <PREFIX>/cache
          root directory of cache into which lib targets are installed

   --libdir=<LIBDIR>
          default: <LIBROOT>/<URI as cache path>
          directory into which lib targets are installed

   --docroot=<DOCROOT>
          default: <PREFIX>/doc
          root directory into which doc targets are installed

   --docdir=<DOCDIR>
          default: <DOCROOT>/<MOGUL as filename>
          directory into which doc targets are installed

   --extractdir=<EXTRACTDIR>
          default: <DIR>
          directory into which to extract a package

   --archive=<ARCHIVE>
          default: http://ww.mozart-oz.org/mogul/pkg
          URL of mogul archive from which packages can be downloaded

   --moguldir=<MOGULDIR>
          directory in which are placed sub-directories for the user's
          contributions: a directory for packages, one for documentation,
          one for mogul database entries.

   --mogulurl=<MOGULURL>
          url corresponding to the <MOGULDIR> directory

  Files

   -m <FILE>, --makefile=<FILE>
          default: <SRCDIR>/makefile.oz
          location of makefile

   -p <PKG>, --package=<PKG>
          file or URL of package. when creating a package, it should be a
          local filename. when extracting or installing, it can also be a
          URL or a mogul id; it the latter case, the package is
          automatically downloaded from the mogul archive

   -V <VERSION>, --packageversion=<VERSION>
          this option is respected by --extract and --install. When
          --extract is given a MOGUL id and downloads the corresponding
          package from the MOGUL archive, it will look precisely for the
          given <VERSION> of the package. --install will simply check
          that the package to be installed really has this <VERSION>.

   --database=<DB>
          default: <PREFIX>/DATABASE
          base path of installed packages database. The database is saved
          in both pickled and textual format respectively in files
          <DB>.ozf and <DB>.txt

  Help

   ozmake --help

   -h, --help
          print this information message

  Build

   ozmake [--build]
          build all targets

   ozmake [--build] FILES...
          build these target

   -b, --build
          this is the default. builds targets of the package

   --optlevel=( none | debug | optimize )
          default: optimize
          select optimization level for compilation

   -g, --debug, --optlevel=debug
          compile with debugging

   -O, --optimize, --optlevel=optimize
          compile with full optimization. this is the default

   --(no)gnu
          is the C++ compiler the GNU compiler. this is determined
          automatically and allows a greater optimization level, namely
          passing -O3 rather than just -O to the compiler

   --(no)fullbuild
          default: false
          also build the src targets

   --includedir DIR, -I DIR
          tell the C++ compiler to additionally search DIR for include
          files

   --(no)sysincludedirs
          default: true
          tell the C++ compiler to additionally search (or not, if using
          --nosysincludedirs) the Mozart-specific include directories
          located in the global installation directory and in the user's
          private ~/.oz area.

   --librarydir DIR, -L DIR
          tell the C++ linker to additionally search DIR for libraries

   --(no)syslibrarydirs
          default: true
          tell the C++ linker to additionally search (or not, if using
          --nosyslibrarydirs) the Mozart-specific library directories
          located in the global installation directory and in the user's
          private ~/.oz area.

  Install

   ozmake --install
          install using the makefile

   ozmake --install FILES...
          install these targets using the makefile

   ozmake --install --package=PKG
          install package PKG

   -i, --install
          install targets of the package and updates the package database

   --grade=( none | same | up | down | any | freshen )
          default: none
          what to do if this package is already installed? ozmake will
          compare version and dates, where the version is more
          significant.

        --grade=none
                signals an error

        --grade=same
                requires versions and dates to be the same

        --grade=up
                requires a package with newer version or same version and
                newer release date than the one installed

        --grade=down
                requires a package with older version or same version and
                older release date than the one installed

        --grade=any
                no conditions

        --grade=freshen
                install if the package is newer else do nothing

   -U, --upgrade
          equivalent to --install --grade=up

   --downgrade
          equivalent to --install --grade=down

   -A, --anygrade
          equivalent to --install --grade=any

   -F, --freshen
          equivalent to --install --grade=freshen

   --(no)replacefiles
          default: false
          allow installation to overwrite files from other packages

   -R, --replace
          equivalent to --install --grade=any --replacefiles

   --(no)extendpackage
          default: false
          whether to replace or extend the current installation of this
          package if any

   -X, --extend
          equivalent to --install --grade=any --extendpackage

   --(no)savedb
          default: true
          save the updated database after installation

   --includedocs, --excludedocs
          default: --includedocs
          whether to install the doc targets

   --includelibs, --excludelibs
          default: --includelibs
          whether to install the lib targets

   --includebins, --excludebins
          default: --includebins
          whether to install the bin targets

   --(no)keepzombies
          default: false
          whether to remove files left over from a previous installation
          of this package

   --exe=( default | yes | no | both | multi )
          default: default
          the convention on Windows is that executables have a .exe,
          while on Unix they have no extension. The --exe option allows
          you to control the conventions used by ozmake when installing
          executables.

        --exe=default
                use the platform's convention

        --exe=yes
                use a .exe extension

        --exe=no
                use no extension

        --exe=both
                install all executables with .exe extension and without

        --exe=multi
                install executable functors for both Unix and Windows.
                The Unix versions are installed without extension, and
                the Windows versions are installed with .exe extension

  Uninstall

   ozmake --uninstall
          uninstall package described by makefile

   ozmake --uninstall --package=PKG
          uninstall package named by mogul id PKG

   -e, --uninstall
          uninstall a package

  Clean

   ozmake --clean
   ozmake --veryclean
          default glob patterns: *~ *.ozf *.o *.so-* *.exe
          remove files as specified by the makefile's clean and veryclean
          features. --veryclean implies --clean.

  Create

   ozmake --create [--package=<FILE>]
          create a package and save it in <FILE>. the files needed for
          the package are automatically computed from the makefile. If
          --package=<FILE> is not supplied, a default is computed using
          the mogul id (and possibly version number) found in the
          makefile.

   --include(bins|libs|docs), --exclude(bins|libs|docs)
          control which target types are included in the package

  Publish

   ozmake --publish
          automatically takes care of all the steps necessary for
          creating/updating a package contributed by the user and making
          all necessary data available to the MOGUL librarian. See
          documentation for --mogul below.

  Extract

   ozmake --extract --package=<PKG>
          extract the files from file or URL PKG. if <PKG> is a mogul id,
          then the package is automatically downloaded from the mogul
          archive

  List

   ozmake --list
          list info for all packages in the installed package database

   ozmake --list --package=<MOGUL>
          list info for the installed package indentified by mogul id
          <MOGUL>

   --linewidth=N
          default: 70
          assume a line with of N characters

  Config

   ozmake --config=put <OPTIONS>
          record the given <OPTIONS> in ozmake's configuration database,
          and use them as defaults in subsequent invocations of ozmake
          unless explicitly overriden on the command line. For example:
          ozmake --config=put --prefix=/usr/local/oz saves /usr/local/oz
          as the default value for option --prefix

   ozmake --config=delete <OPT1> ... <OPTn>
          deletes some entries from the configuration database. For
          example: ozmake --config=delete prefix removes the default for
          --prefix from the configuration database

   ozmake --config=list
          lists the contents of ozmake's configuration database

   the argument to --config can be abbreviated to any non-ambiguous
   prefix

  Mogul

   If you choose to contribute packages to the MOGUL archive, ozmake
   --mogul=<ACTION> simplifies your task. It makes it easy for you to
   maintain a database of your contributions and to export them so that
   the MOGUL librarian may automatically find them. In fact, the simplest
   way is to use ozmake --publish which will take take care of all
   defails for you.

   ozmake --mogul=put
          update the user's database of own mogul contributions with the
          data for this contribution (in local directory)

   ozmake --mogul=put --package=<PKG>
          same as above, but using the package <PKG> explicitly given

   ozmake --mogul=delete <MOG1> ... <MOGn>
          remove the entries with mogul ids <MOG1> through <MOGn> from
          the user's database of own contribution

   ozmake --mogul=delete
          remove entry for current contribution

   ozmake --mogul=list
          show the recorded data for all entries in the user's database
          of own mogul contributions

   ozmake --mogul=list <MOG1> ... <MOGn>
          show the recorded data for entries <MOG1> through <MOGn> in the
          user's database of own mogul contributions

   ozmake --mogul=export
          write all necessary mogul entries for the user's own mogul
          contributions. These are the entries which will be read by the
          MOGUL librarian to automatically assemble the full MOGUL
          database.

   The data for your contributions need to be made available to the MOGUL
   librarian on the WEB. You want to just update a local directory with
   your contributions, but, in order for the MOGUL librarian to find
   them, these directories must also be available through URLs on the
   WEB. Here are some options that allow you to control this
   correspondance, and for which you should set default using ozmake
   --config=put

   --moguldir=<MOGULDIR>
   --mogulurl=<MOGULURL>
          <MOGULDIR> is a directory which is also available on the WEB
          through url <MOGULURL>. <MOGULDIR> is intended as a root
          directory in which sub-directories for packages, documentation,
          and mogul entries will be found.

   For those who really enjoy pain, ozmake has of course many options to
   shoot yourself in the foot. In the options below <ID> stands for the
   filename version of the package's mogul id (basically replace slashes
   by dashes). You can control where packages, their documentation and
   mogul database entries and stored and made available using the options
   below:

   --mogulpkgdir=<MOGULPKGDIR>
          default: <MOGULDIR>/pkg/<ID>/

   --mogulpkgurl=<MOGULPKGURL>
          default: <MOGULURL>/pkg/<ID>/

   --moguldocdir=<MOGULDOCDIR>
          default: <MOGULDIR>/doc/<ID>/

   --moguldocurl=<MOGULDOCURL>
          default: <MOGULURL>/doc/<ID>/

   --moguldbdir=<MOGULDBDIR>
          default: <MOGULDIR>/db/<ID>/

   --moguldburl=<MOGULDBURL>
          default: <MOGULURL>/db/<ID>/

   Your contributions should all have mogul ids which are below the mogul
   id which you where granted for your section of the mogul database. For
   convenience, ozmake will attempt to guess the root mogul id of your
   section as soon as there are entries in your database of your own
   contributions. However, it is much preferable to tell ozmake about it
   using:

   --mogulrootid=<ROOTID>

   and to set it using ozmake --config=put --mogulrootid=<ROOTID>

MAKEFILE

   The makefile contains a single Oz record which describes the project
   and should normally be placed in a file called makefile.oz. A makefile
   typically looks like this:
        makefile(
          lib : ['Foo.ozf']
          uri : 'x-ozlib://mylib'
          mogul : 'mogul:/denys/lib-foo')

   stating explicitly that there is one library target, namely the
   functor Foo.ozf, and that it should installed at URI:
        x-ozlib://mylib/Foo.ozf

   and implicitly that it should be compiled from the Oz source file
   Foo.oz. When you invoke ozmake --install, the mogul feature serves to
   uniquely identify this package and the files it contributes in the
   ozmake database of installed packages.

   There are many more features which can occur in the makefile and they
   are all optional. If you omit all the features, you only get the
   defaults and you don't even need a makefile. All values, suchs as
   files, should be given as virtual string; atoms are recommended except
   for features blurb, info_text and info_html, where strings are
   recommended.
        makefile(
          bin      : [ FILES... ]
          lib      : [ FILES... ]
          doc      : [ FILES... ]
          src      : [ FILES... ]
          depends  :
             o( FILE : [ FILES... ]
                ...
              )
          rules    :
             o( FILE : TOOL(FILE)
                ...
              )
          clean     : [ GLOB... ]
          veryclean : [ GLOB... ]
          uri       : URI
          mogul     : MOGUL
          author    : [ AUTHORS... ]
          released  : DATE
          blurb     : TEXT
          info_text : TEXT
          info_html : TEXT
          subdirs   : [ DIRS... ]
          requires  : [ MOGUL... ]
          categories: [ CATEGORY... ]
          version   : VERSION
          provides  : [ FILES... ]
        )

   Features bin, lib and doc list targets to be installed in <BINDIR>,
   <LIBDIR> and <DOCDIR> respectively. bin targets should be executable
   functors, i.e. they should end with extension .exe. lib targets are
   typically compiled functors i.e. ending with extension .ozf, but could
   also be native functors, i.e. ending with extension .so, or simply
   data files. doc targets are documentation files.

  Extensions

   ozmake knows how to build targets by looking at the target's
   extension:
   Foo.exe
          is an executable functor and is created from Foo.ozf
   Foo.ozf
          is a compiled functor and is created from Foo.oz
   Foo.o
          is a compiled C++ file and is created from Foo.cc
   Foo.so
          is a native functor and is created from Foo.o
   Foo.cc
          is a C++ source file
   Foo.hh
          is a C++ header file

   Note that these are abstract targets. In particular, Foo.so really
   denotes the file Foo.so-<PLATFORM> where <PLATFORM> identifies the
   architecture and operating system where the package is built; for
   example: linux-i486. Also, when a bin target Foo.exe is installed, it
   is installed both as <BINDIR>/Foo.exe and <BINDIR>/Foo so that it can
   be invoked as Foo on both Windows and Unix platforms.

   It is imperative that you respect the conventional use of extensions
   described here: ozmake permits no variation and supports no other
   extensions.

  Rules

   ozmake has built-in rules for building files. Occasionally, you may
   want to override the default rule for one or more targets. This is
   done with feature rule which contains a record mapping target to rule:
        TARGET_FILE : TOOL(SOURCE_FILE)

   the rule may also have a list of options:
        TARGET_FILE : TOOL(SOURCE_FILE OPTIONS)

   The tools supported by ozmake are ozc (Oz compiler), ozl (Oz linker),
   cc (C++ compiler), ld (C++ linker). The default rules are:
        'Foo.exe' : ozl('Foo.ozf' [executable])
        'Foo.ozf' : ozc('Foo.oz')
        'Foo.o'   : cc('Foo.cc')
        'Foo.so'  : ld('Foo.o')

   The tools support the following options:
   ozc
        executable
               make the result executable
        'define'(S)
               define macro S. Same as -DS on the command line
   ozl
        executable
               make the result executable
   cc
        include(DIR)
               Similar to the usual C++ compiler option -IDIR. DIR is a
               virtual string
        'define'(MAC)
               Similar to the usual C++ compiler option -DMAC. MAC is a
               virtual string
   ld
        library(DIR)
               Similar to the usual C++ linker option -lDIR. DIR is a
               virtual string

   You might want to specify a rule to create a pre-linked library:
        'Utils.ozf' : ozl('Foo.ozf')

   or to create a non-prelinked executable:
        'Foo.exe' : ozc('Foo.oz' [executable])

  Dependencies

   ozmake automatically determines whether targets needed to be rebuilt,
   e.g. because they are missing or if some source file needed to create
   them has been modified. The rules are used to determine dependencies
   between files. Sometimes this is insufficient e.g. because you use
   tool ozl (dependencies on imports), or \insert in an Oz file, or
   #include in a C++ file. In this case you can specify additional
   dependencies using feature depends which is a record mapping targets
   to list of dependencies:
        TARGET : [ FILES... ]

   For example:
        'Foo.o' : [ 'Foo.hh' 'Baz.hh' ]

   or
        'Foo.exe' : [ 'Lib1.ozf' 'Lib2.ozf' ]

  Cleaning

   During development, it is often convenient to be able to easily remove
   all junk and compiled files to obtain again a clean project directory.
   This is supported by ozmake --clean and ozmake --veryclean; the latter
   also implies the former. Files to be removed are specified by glob
   patterns where ? matches any 1 character and * matches a sequence of 0
   or more characters. All files in BUILDDIR matching one such pattern is
   removed. There are built-in patterns, but ou can override them with
   features clean and veryclean which should be lists of glob patterns.
   For example the default clean glob patterns are:
        clean : [ "*~" "*.ozf" "*.o" "*.so-*" "*.exe" ]

  Package Related Features

    uri

   feature uri indicates the URI where to install lib targets. For
   example:
        uri : 'x-ozlib://mylib/XML'

   states that all lib targets (e.g. Foo.ozf) will be installed under
   this URI so that they can also be imported from it, i.e.:
       import MyFoo at 'x-ozlib://mylib/XML/Foo.ozf'

    mogul

   feature mogul is the mogul id uniquely identifying this package. It is
   used to identify the package in the database of installed packages, to
   create/publish the package, and to install its documention files.

    author

   feature author is a virtual string or list of virtual string resp.
   identifying the author or authors of the package. It is recommended to
   identify authors by their mogul id, however is is also possible to
   simply give their names. For example, the recommended way is:
        author : 'mogul:/duchier'

   but the following is also possible:
        author : 'Denys Duchier'

    released

   feature released is a virtual string specifying the date and time of
   release in the following format:
        released : "YYYY-MM-DD-HH:MM:SS"

   time is optional. An appropriate release date using the currentdate
   and time is automatically inserted when invoking ozmake --create or
   ozmake --publish.

    blurb

   feature blurb contains a very short piece of text describing the
   package. This text should be just one line and is intended to be used
   as a title when the package is published in the mogul archive.

    info_text

   feature info_text contains a plain text description of the package.
   This is intended to be used as an abstract on the presentation page
   for the package in the mogul archive. It should be brief and
   informative, but should not attempt to document the package.

    info_html

   feature info_html is similar to info_text but contains HTML rather
   than plain text.

    src

   feature src indicates which targets should be considered source, i.e.
   in particular non-buildable. All targets mentioned in src should be
   mentioned in bin, lib, or doc too. The point of src is to support
   distributing packages with pre-built targets and without giving out
   the corresponding sources. You should not do this with native functors
   since they are platform dependent and not portable, but it can be a
   convenient means of distributing prebuilt Oz libraries. For example:
        makefile(
          lib : [ 'Foo.ozf' ]
          src : [ 'Foo.ozf' ]
          uri : 'x-ozlib://mylib'
          mogul : 'mogul:/myname/foolib')

   is a makefile for a package that distribute the precompiled Foo.ozf,
   but does not also distribute its source Foo.oz. Normally, when you
   build a package it simply checks that the src files are present but
   will not attempt to build them. If you have the sources, you can force
   building the src targets if necessary using --fullbuild.

    subdirs

   feature subdirs is a list of bare filenames representing
   subdirectories of the project. By default, when necessary, ozmake will
   recurse into these subdirectories. It is expected that each
   subdirectory should provide its own makefile. The mogul id is
   automatically inherited to subdirectories and the uri is automatically
   extended by appending the name of the subdirectory: thus submakefiles
   can be simpler since they don't need to be concerned with
   package-level features.

    requires

   feature requires is a list of module URIs or package MOGUL ids. These
   represent the external dependencies of the package. They are not yet
   used, but eventually ozmake will be able to use them to automate the
   recursive installation of other packages required by the one you are
   interested in.

    categories

   feature categories is a list of MOGUL categories to help categorize
   this package in the MOGUL archive.

    version

   feature version is used to provide a version string. This is a string
   that consist of integers separated by single dots, e.g. "2" or
   "3.1.7".

    provides

   feature provides is used to override the default information about
   what the package provides, normally automatically computed from the
   bin and lib targets: it should be a list which contains a subset of
   these targets. The provides feature of a makefile does not override or
   otherwise affect its submakefiles: each makefile should separately
   override if it so desires. To state that a makefile does not
   officially provide any functors or executable application, you would
   add:
        provides : nil

   You should use the provides feature when your package contains both
   official public functors as well as purely implementational functors
   that are not part of the official public interface and should not be
   mentioned as provided by the package.

CONTACTS

   Authors should really be referred to by mogul ids denoting mogul
   entries that describe them. In order to make this easier, a
   makefile.oz may also contain a contact feature which is either a
   record describing a person, or a list of such records.

   You should not have a contact feature in every makefile. Rather, the
   contact feature is usually intended for makefiles that only have a
   contact feature, i.e. whose only purpose is to create mogul entries
   for the corresponding persons. Here is an example of such a makefile:
        makefile(
           contact :
              o(
                 mogul : 'mogul:/duchier/denys'
                 name  : 'Denys Duchier'
                 email : 'duchier@ps.uni-sb.de'
                 www   : 'http://www.ps.uni-sb.de/~duchier/'))

   You can invoke ozmake --publish on such a makefile to contribute the
   corresponding mogul database entries
     _________________________________________________________________


    [3]Denys Duchier

References

   1. http://www.ps.uni-sb.de/~duchier/
   2. file://localhost/home/denys/src/Mozart/devel/stdlib/ozmake/CHANGES
   3. http://www.ps.uni-sb.de/~duchier/
