ozskel utilities

Denys Duchier

provides
ozskel
ozinstall
requires
GNU autoconf (for the developer)
GNU make (for installation)
GNU tar (optionally, for creating .tgz archives)


ozskel

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


ozinstall

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