ozskel utilities
Denys Duchier
- provides
- ozskel
- ozinstall
- requires
- GNU autoconf (for the developer)
- GNU make (for installation)
- GNU tar (optionally, for creating
.tgz archives)
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.
- config.guess
- config.sub
- install-sh
- ozinstall
- auxiliary scripts for configuration and installation.
- Package.mogul
- Example of MOGUL
package entry.
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.
Targets
make all
- builds the package
make install
- builds and installs the package
make install.top
make install.aux
make install.bin
make install.doc
make install.api
- builds and installs part of the package.
make api
- creates the API documentation by invoking
ozh
make clean
make veryclean
make distclean
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.
make tgz
make tarz
- creates a source distribution archive, resp.
$(PKG_NAME).tgz and $(PKG_NAME).tar.Z
make update
- 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_URI
mogul:/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_URI
mogul:/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.
Usage
ozinstall OPTIONS -d DIR
- if directory DIR is not present, it is created.
ozinstall OPTIONS [-f|-x|-M] SRCFILE DSTFILE
ozinstall OPTIONS [-f|-x|-M] SRCFILE DSTDIR/
ozinstall OPTIONS [-f|-x|-M] SRCFILE -d DSTDIR
- 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).
Environment Variables
OZSKEL_MODE_DIR
- default mode for directories (initially 775)
OZSKEL_MODE_FILE
- default mode for data files (initially 444)
OZSKEL_MODE_BIN
- default mode for executable files (initially 555)
Denys Duchier