xenial (1) ozmake.1.gz

Provided by: mozart-stdlib_20060615-6_all bug

NAME

       Ozmake - Make for Oz

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) ...

       DESCRIPTION
       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.

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://www.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; in 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
              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 identified 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 overridden 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 details 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 correspondence, 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, such 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 you  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 documentation
       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 current date 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 pre-built 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 pre-compiled 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 sub-makefiles 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 sub-makefiles: 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

AUTHOR

       This man page has been automatically generated from the  ozmake  help  file.  The  ozmake  help  file  is
       maintained by Denys Duchier.

SEE ALSO

       Full  documentation  of  the  Mozart  system and the Oz programming language is available through the the
       mozart-doc package, or from the mozart web page www.mozart-oz.org.  See in particular the document The Oz
       Programming Interface.

       ozc(1), ozd(1), ozengine(1), ozl(1), oztool(1), convertTextPickle(1).

                                                  June 3, 2005                                         OZMAKE(1)