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