ozmake is now in beta-release - feedback is extremely welcome
see CHANGES for a list of changes between
successive versions of
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.
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) ...
In the following, we write meta variables between angle brackets, e.g. <PREFIX> or <URI as cache path>
-v, --verbose
-q, --quiet
-n, --just-print
--local
--(no)autodepend
true
import and require sections.
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.
--prefix=<PREFIX>
~/.oz
--dir=<DIR>
--builddir=<BUILDDIR>
--srcdir=<SRCDIR>
--bindir=<BINDIR>
<PREFIX>/bin
bin targets are placed--libroot=<LIBROOT>
<PREFIX>/cache
lib targets are
installed--libdir=<LIBDIR>
<LIBROOT>/<URI as cache path>
lib targets are installed--docroot=<DOCROOT>
<PREFIX>/doc
doc targets are
installed--docdir=<DOCDIR>
<DOCROOT>/<MOGUL as filename>
doc targets are installed--extractdir=<EXTRACTDIR>
--archive=<ARCHIVE>
http://ww.mozart-oz.org/mogul/pkg
--moguldir=<MOGULDIR>
--mogulurl=<MOGULURL>
-m <FILE>, --makefile=<FILE>
<SRCDIR>/makefile.oz
-p <PKG>, --package=<PKG>
-V <VERSION>, --packageversion=<VERSION>
--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>
<PREFIX>/DATABASE
<DB>.ozf and
<DB>.txt
ozmake --help
-h, --help
ozmake [--build]
ozmake [--build] FILES...
-b, --build
--optlevel=( none | debug | optimize )
optimize
-g, --debug, --optlevel=debug
-O, --optimize, --optlevel=optimize
--(no)gnu
-O3 rather than just -O to the
compiler
--(no)fullbuild
false
src targets--includedir DIR, -I DIR
DIR for include files--(no)sysincludedirs
true
--nosysincludedirs) the Mozart-specific include
directories located in the global installation directory and in the
user's private ~/.oz area.--librarydir DIR, -L DIR
DIR for libraries--(no)syslibrarydirs
true
--nosyslibrarydirs) the Mozart-specific library
directories located in the global installation directory and in the
user's private ~/.oz area.ozmake --install
ozmake --install FILES...
ozmake --install --package=PKG
PKG
-i, --install
--grade=( none | same | up | down | any | freshen )
none
--grade=none
--grade=same
--grade=up
--grade=down
--grade=any
--grade=freshen
-U, --upgrade
--install --grade=up
--downgrade
--install --grade=down
-A, --anygrade
--install --grade=any
-F, --freshen
--install --grade=freshen
--(no)replacefiles
false
-R, --replace
--install --grade=any --replacefiles
--(no)extendpackage
false
-X, --extend
--install --grade=any --extendpackage
--(no)savedb
true
--includedocs, --excludedocs
--includedocs
doc targets--includelibs, --excludelibs
--includelibs
lib targets--includebins, --excludebins
--includebins
bin targets--(no)keepzombies
false
--exe=( default | yes | no | both | multi )
default
.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
--exe=yes
.exe extension--exe=no
--exe=both
.exe extension and
without--exe=multi
.exe extensionozmake --uninstall
ozmake --uninstall --package=PKG
PKG
-e, --uninstall
ozmake --clean
ozmake --veryclean
*~ *.ozf *.o *.so-* *.exe
--veryclean implies
--clean.
ozmake --create [--package=<FILE>]
--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)
ozmake --publish
--mogul below.
ozmake --extract --package=<PKG>
ozmake --list
ozmake --list --package=<MOGUL>
--linewidth=N
N charactersozmake --config=put <OPTIONS>
ozmake --config=put --prefix=/usr/local/oz
saves /usr/local/oz as the default value for option
--prefix
ozmake --config=delete <OPT1> ... <OPTn>
ozmake --config=delete prefix
removes the default for --prefix from the configuration databaseozmake --config=list
the argument to --config can be abbreviated to any non-ambiguous
prefix
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
ozmake --mogul=put --package=<PKG>
ozmake --mogul=delete <MOG1> ... <MOGn>
ozmake --mogul=delete
ozmake --mogul=list
ozmake --mogul=list <MOG1> ... <MOGn>
ozmake --mogul=export
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>
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>
--mogulpkgurl=<MOGULPKGURL>
--moguldocdir=<MOGULDOCDIR>
--moguldocurl=<MOGULDOCURL>
--moguldbdir=<MOGULDBDIR>
--moguldburl=<MOGULDBURL>
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>
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.
ozmake knows how to build targets by looking at the target's extension:
Foo.exe
Foo.ozf
Foo.ozf
Foo.oz
Foo.o
Foo.cc
Foo.so
Foo.o
Foo.cc
Foo.hh
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.
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:
executable
'define'(S)
S. Same as -DS on the command lineexecutable
include(DIR)
-IDIR. DIR is a virtual
string'define'(MAC)
-DMAC. MAC is a virtual
stringlibrary(DIR)
-lDIR. DIR is a virtual
stringYou 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])
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' ]
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" ]
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'
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.
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'
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.
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.
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.
feature info_html is similar to info_text but
contains HTML rather than plain text.
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.
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.
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.
feature categories is a list of MOGUL categories to help
categorize this package in the MOGUL archive.
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".
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.
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