ozskel utilities

Purpose

ozskel is a script that creates all the administrative
files that you need to make it easy to configure, build,
and install a mozart package. For example, it provides you
with a well designed Makefile.in where you mostly only need
to fill in the blanks. More precisely, it creates the following
files:

Package.html

the squeleton of a html file that you can use to document your
package. You should rename this file appropriately,
e.g. index.html

Makefile.in

you should fill in the blanks and extend this file, but you
should preserve its design for uniformity across all Mozart
packages.

configure

A ready-made version of the configure script, created by
autoconf from configure.in and included in the
default set up, since few developers need to modify
configure.in. This means you normally won't need to have
autoconf installed on your system.

aclocal.m4

some m4 macros for autoconf.

configure.in

unless your package has special configuration needs, you
probably don't have to touch this file.

Installation

This package can be installed by following the usual
configure, build, install procedure, i.e. by executing in a
shell:
./configure
make install
This builds the ozskel script and installs it in directory
~/.oz/bin by default and its documentation in
~/.oz/doc/bin/ozskel/. You can override this e.g. using:
make install PREFIX=/usr/local/oz
which will use /usr/local/oz/ instead of ~/.oz/

Usage

When developing a new package, first create a directory for it and
use ozskel to populate it with administrative files, e.g.:
mkdir snap-crackle-pop
cd snap-crackle-pop
ozskel
There is already a configure script available, however you
should remember to invoke autoconf again whenever you modify
configure.in or aclocal.m4.

ozskel -m

this just creates the Makefile.in and is convenient to
invoke in a subdirectory. If the subdirectory is called foo,
remember to add foo/Makefile in file configure.in in
the call to the AC_OUTPUT macro. Then you must also invoke
autoconf in order to recompute configure.

Makefile.in

Makefile.in is the template that is instantiated when the
user invokes configure. Mostly, you should just have to
provide values for some of its variables and perhaps add a few
dependencies. Rarely do you need to do more: this template
anticipates most usual needs of a package developer.

Fill In The Blanks

PKG_NAME

The name of your package. For example the name of the `ozskel'
package is duchier-ozskel. This is used as the base name for
creating distribution files, e.g. with .tgz and .zip
extensions. Make sure you pick a name such that adding a
.tgz or .zip extension results in a file name that
does not conflict with any file or directory existing or created by
your package.

PKG_MOGUL_URI

This is the URI that uniquely identifies your package in the
MOGUL Database. You
are strongly urged to become a contributor to MOGUL, The MOzart Global
User Library, but you don't have to. PKG_MOGUL_URI is used
to determine where to install your package's documentation.

PKG_URI

This is the base URI for the modules in your package. This is
what is going to be used in import specifications. It is
very important to assigned a fixed URI to your package: this is how
its modules can be imported, i.e. reused, by other applications. When
your package is installed, its modules are placed in the user's cache
under this URI.

PKG_URI_AUX

This is a sub URI for auxiliary modules and files that you don't
want to expose at the same level as the base URI, but prefer to
isolate in their own directory.

PKG_SOURCES

All the source files for your application. This is one possible
way of creating source distributions, but see PKG_METHOD for
an alternative.

PKG_INSTALLS

These are the filenames of the main modules and data files of your
package, e.g. Foo.ozf i.e. the name of the compiled functor
Foo. They are used to determine what needs to be installed
at the main URI PKG_URI and, therefore what needs to be
built.

PKG_INSTALL_AUX

Auxiliary modules and files to be installed at the auxiliary URI
PKG_URI_AUX. Note that this is often used for data files
such as GIF files etc...

PKG_INSTALLS_DOC

Documentation files to be installed, and, therefore to be built if
necessary. Documentation files are installed in a directory computed
from PKG_MOGUL_URI. For example, if PKG_MOGUL_URI
is mogul:/sherlock/baker-street/pipe
then the documentation is installed in
$(DOCDIR)/sherlock/baker-street/pipe

PKG_INSTALLS_BIN

scripts or executable functors to be installed in
$(BINDIR)

PKG_INSTALLS_INC

include files to be installed under $(INCDIR). For example if
PKG_INSTALLS_INC is toby.hh and
PKG_MOGUL_URI is
mogul:/sherlock/baker-street/toby.hh
then the include file is installed as:
$(INCDIR)/sherlock/baker-street/toby.hh

PKG_SUBDIRS

The source of your package can be organized in sub-directories.
You should set PKG_SUBDIRS to the list of immediate
directories into which make should recurse. For example if
your package has subdirectories baker-street and
watson that also need to be `made', then use the following
setting:
PKG_SUBDIRS = baker-street watson
See Package Sub Directories for more info.

PKG_API

A list of source functor files to hand to
ozh for creating the API documentation.

PKG_METHOD

determines how a source archive is constructed. If
PKG_METHOD is find, then the find program
is invoked to automatically compute a list of source files. It does
this by exploring your source tree and has good defaults about what
files and directories to ignore (e.g. CVS
directories, compiled files, backup files ... see FIND_OPTIONS in
Makefile.in). If PKG_METHOD is make then
it is up to the Makefile (as well as the Makefiles
in sub-directories) to decide what files to put into the archive.
This is realized by setting variable PKG_SOURCES in each
Makefile. If PKG_METHOD is not set, it defaults to
make if PKG_SOURCES is non-empty and to
find otherwise. Note that this decision is effected in the
directory where you invoke make and passed on to
sub-directories so that they all use the same method.

PKG_UPDATE

This is a list of abstract update targets in the set
tgz, tarz and zip. The default
is just tgz. Target tgz creates a
.tgz source archive distribution, tarz a
.tar.Z (for platforms that do not have gzip), and
zip a .zip archive.

Makefile.vars and Makefile.rules

You may find it preferable to provide your customizations in files
Makefile.vars and Makefiles.rules. These are
automatically included by the Makefile.
Makefile.vars is included just after the default settings for
the PKG_... variables, thus allowing you to override them.
Makefile.rules is included at the very end, thus allowing you
to provide additional rules while being able to take advantage of
variable settings computed by the rest of the file.

clean is for removing all files created by the build
process, veryclean additionally removes the API
documentation directory, and distclean additionally
removes all files created by the configuration process.

executes make $(PKG_UPDATE), then installs the
resulting archives in $(PKGDIR) i.e. typically
~/.oz/pkg. This is intended for developers who make their
applications available in MOGUL and instruct the MOGUL Librarian to
fetch updates automatically from a url corresponding to directory
$(PKGDIR)

make zip

preliminary support for creating binary zip distributions.

make debug-XXX

This is like make XXX but adds debugging flags for
compilation.

Directories

Do not change any of the variables documented here. They provide a
uniform installation interface for all packages and are automatically
instantiated by the configuration process. A package installs
into the directory tree specified by PREFIX:

SRCDIR

the source directory of your package. We distinguish between
`source' and `build' directories. You can build in a directory that
is not the same as the source directory. Suppose the source is in
directory /user/kellogg/snap-crackle-pop and you create a
build directory /user/tiger/breakfast. You can then
configure, build and install the package as follows:
cd /user/tiger/breakfast
/user/kellogg/snap-crackle-pop/configure
make install

BUILDDIR

the build directory.

PREFIX

This is the root of the directory tree in which the package will
be installed. It defaults to ~/.oz which is the user's
private area for mozart packages. You can effect a site global
installation either by
make install PREFIX=/usr/local/oz
or by causing the default to be different during configuration:
./configure --prefix=/usr/local/oz

CACHE = $(PREFIX)/cache

This is the user's cache. A module with URI
x-ozlib://kellogg/Snap.ozf is installed in
$(CACHE)/x-ozlib/kellogg/Snap.ozf

DOCDIR = $(PREFIX)/doc

For a package with PKG_MOGUL_URImogul:/sherlock/baker-street/pipe, the documentation is
installed in $(DOCDIR)/sherlock/baker-street/pipe

BINDIR = $(PREFIX)/bin

When a package provides scripts or executable functors, these may be
installed in BINDIR. However, we discourage installing
executable functors in BINDIR since this might cause two
packages to step on each others toes. For example, if the package
makes available the executable functor
x-ozlib://kellogg/breakfast.exe, it can simply be invoked
from the shell as follows:
ozengine x-ozlib://kellogg/breakfast.exe
The Mozart resolver mechanism will automatically find it in your
cache.

INCDIR = $(PREFIX)/include

This is where include files are installed. For a package with
PKG_MOGUL_URImogul:/sherlock/baker-street/pipe, include files are
installed in $(INCDIR)/sherlock/baker-street/pipe

PKGDIR = $(PREFIX)/pkg

This is only of interest to MOGUL contributors (do consider
becoming one and making your creations available to the rest of the
Mozart user community). PKGDIR is where distribution
archives are placed. Typically, this will be a directory that you
will arrange to make also accessible from your home page (e.g. by
drawing a symbolic link).

Environment Variables

The configuration process can also be parametrized through
environment variables

OZSKEL_PREFIX

This can be used to provide a different default value for
PREFIX. If you always want to install globally, you
could do (in bash):
export OZSKEL_PREFIX=/usr/local/oz
or (in csh):
setenv OZSKEL_PREFIX /usr/local/oz

Purpose

ozinstall is a shell script to install files and
directories. It is hopefully written in pure sh and thus
should be maximally portable. It assumes the existence of
cp, mkdir, chmod, and chgrp, and
further assumes that cp supports the -f flag
(force).

ozinstall makes it unnecessary to fight hordes of
incompatible install programs and covers concisely all the
cases useful for Mozart packages. An `install' script must in any case
be included in any distributed package to permit installation on
machines which do not have an install program. We might as
well always use ozinstall.

One feature of ozinstall is that it will automatically
create the destination directory structure. This greatly simplifies
Makefiles since no rules are necessary to create installation
directories.

SRCFILE is installed as DSTFILE. If the
directory of DSTFILE does not yet exist, it is
created. -f installs a regular data file, -x
installs an executable, and -M decides which of -f
and -x to use based on whether SRCFILE is executable
or not.

Options

-g GROUP
--group GROUP
--group=GROUP

sets the group to use for newly created files and directories.

-m MODE
--mode MODE
--mode=MODE

sets the mode to use for explicit file or directory creation.
This will not be used for implicit directory creation (see
OZSKEL_MODE_DIR).