Provided by: mozart-stdlib_20060615-6_all 
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)