Syntax

The _oasis must be a valid UTF-8 text file. This file identify the toplevel directory of the project.

Identifiers are just like variable names in OCaml, it cannot contains "-" or numbers at the beginning. Strings follow OCaml convention. For extra information on the parser/lexer see Genlex.

A line beginning by # is a comment and is ignored. Blank line are ignored.

The file contains semi-colon fields and sections.

Library foo

Library "foo".

Library "foo"
  # Library fields 
  Path: src/

# Back to toplevel fields
Synopsis: bar

ocamlc -config

Package

Package fields are defined outside sections. They apply to the whole project.

Fields:

• OASISFormat: OASIS format version used to write file _oasis. (mandatory)
• Name: Name of the package. (mandatory)
• Version: Version of the package. (mandatory)
• Synopsis: Short description of the purpose of this package. (mandatory)
• Description: Long description of the package purpose.
• Authors: Real people that had contributed to the package. (mandatory)
• Copyrights: Copyright owners.
• Maintainers: Current maintainers of the package.
• LicenseFile: File containing the license.
• License: DEP-5 license of the package (See DEP-5). (mandatory)
• OCamlVersion: Version constraint on OCaml.
• FindlibVersion: Version constraint on Finblib.
• ConfType: Configuration system.
• PreConfCommand: Command to run before configuration.
• PostConfCommand: Command to run after configuration.
• BuildType: Build system.
• PreBuildCommand: Command to run before build.
• PostBuildCommand: Command to run after build.
• InstallType: Install/uninstall system.
• PreInstallCommand: Command to run before install.
• PostInstallCommand: Command to run after install.
• PreUninstallCommand: Command to run before uninstall.
• PostUninstallCommand: Command to run after uninstall.
• PreCleanCommand: Command to run before clean.
• PostCleanCommand: Command to run after clean.
• PreDistcleanCommand: Command to run before distclean.
• PostDistcleanCommand: Command to run after distclean.
• Homepage: URL of the package homepage.
• Categories: URL(s) describing categories of the package.
• FilesAB: Files to generate using environment variable substitution.
• Plugins: Extra plugins to use.
• BuildDepends: Dependencies on findlib packages, including internal findlib packages.
• BuildTools: Tools required to compile, including internal executables.

BuildDepends and BuildTools are appended to all sections and not used directly in the package.

Sections

There are 6 possible sections:

• Flag: a command line flag.
• Library: an OCaml library.
• Executable: an OCaml executable.
• Document: a document.
• Test: a test.
• SourceRepository: version control system information.

None of these sections are mandatory. Library, Executable, Document and Test can be dependent on each other. This not a problem as long as there is no cycle inside the dependency graph. Dependencies can be expressed through BuildDepends and BuildTools fields.

License

We have adopted a DEP-5 license style description.

The reason of this format is to have machine-readable license description. Using this former work, we hope to be compatible with future standards of Debian.

We have limited the number of license to:

• Apache: Apache license (versions 1.0, 1.1, 2.0)
• Artistic: Artistic license (versions 1.0, 2.0)
• BSD3: Berkeley software distribution license (3 clauses)
• BSD4: Berkeley software distribution license (4 clauses)
• CC-BY: Creative Commons Attribution license
• CC-BY-NC: Creative Commons Attribution Non-Commercial
• CC-BY-NC-ND: Creative Commons Attribution Non-Commercial No Derivatives
• CC-BY-NC-SA: Creative Commons Attribution Non-Commercial Share Alike
• CC-BY-ND: Creative Commons Attribution No Derivatives
• CC-BY-SA: Creative Commons Attribution Share Alike license
• CC0: Creative Commons Universal waiver
• CDDL: Common Development and Distribution License
• CeCILL: CEA-CNRS-INRIA Logiciel Libre. GPL like. (versions 1, 2)
• CeCILL-B: CEA-CNRS-INRIA Logiciel Libre, BSD-like
• CeCILL-C: CEA-CNRS-INRIA Logiciel Libre, LGPL-like
• CPL: IBM Common Public License (version 1.0)
• Eiffel: The Eiffel Forum License (version 2)
• Expat: The Expat license
• FreeBSD: FreeBSD Project license
• GFDL: GNU Free Documentation License (versions 1.1, 1.2, 1.3)
• GFDL-NIV: GNU Free Documentation License, with no invariant sections (versions 1.1, 1.2, 1.3)
• GPL: GNU General Public License (versions 1.0, 2.0, 3.0)
• ISC: Internet Software Consortium's license. Sometimes also known as the OpenBSD License.
• LGPL: GNU Lesser General Public License. GNU Library General Public License for versions lower than 2.1 (versions 2.0, 2.1, 3.0)
• LPPL: LaTeX Project Public License (version 1.3c)
• MIT: MIT License
• MPL: Mozilla Public License (versions 1.0, 1.1)
• PD: Public domain. This is not a true license.
• Perl: Perl license. Equates to GPL-1+ or Artistic-1.
• PROP: Proprietary license, all rights reserved
• PSF: Python Software Foundation license (version 2)
• QPL: Q Public License (version 1.0)
• W3C-Software: W3C Software License (version 20021231)
• ZLIB: zlib/libpng license (version 1.2.2)
• Zope: Zope Public License (versions 1.0, 2.0, 2.1)
• or an URL describing the license

And license exception to:

• OCaml linking compatible with LGPL: Add an exception to allow static compilation without license propagation. Without this clause, compiling against an OCaml library force license propagation. The LGPL is equal to GPL without this exception.
• or an URL describing the license exception

You can specify a license version using a dash and only digits or dashes at the end of the license short name.

Examples :

• LGPL-2.1 with OCaml linking exception: LGPL v2.1 with OCaml linking exception
• GPL-2+: GPL v2 or later

Data files

DataFiles fields help to install extra data inside $datadir/$pkg_name. This field is a comma separated list of file, with optional value inside parenthesis. You can override target directory using fn ($datadir/other_location).

You can use wildcard * but only for a filename and followed by a single dot extension: dir/*.html is valid but dir/* and dir/*.tar.gz are not valid.

Substitution inside text

Substitution is performed using Buffer.add_substitute.

Variable are evaluated using environment. This is a mix of various data coming from _oasis file, ocamlc -config output and configure tests. So environment variables depends of each project. You can have a precise idea of what variables is available looking at the file setup.data.

Here is a list of standard variables:

• ocamlfind
• ocamlc
• ocamlopt
• ocamlbuild
• pkg_name: Package name
• pkg_version: Package version
• os_type
• system
• architecture
• ccomp_type
• ocaml_version
• standard_library_default
• standard_library
• standard_runtime
• bytecomp_c_compiler
• native_c_compiler
• model
• ext_obj
• ext_asm
• ext_lib
• ext_dll
• default_executable_name
• systhread_supported
• prefix: Install architecture-independent files dir
• exec_prefix: Install architecture-dependent files in dir
• bindir: User executables
• sbindir: System admin executables
• libexecdir: Program executables
• sysconfdir: Read-only single-machine data
• sharedstatedir: Modifiable architecture-independent data
• localstatedir: Modifiable single-machine data
• libdir: Object code libraries
• datarootdir: Read-only arch-independent data root
• datadir: Read-only architecture-independent data
• infodir: Info documentation
• localedir: Locale-dependent data
• mandir: Man documentation
• docdir: Documentation root
• htmldir: HTML documentation
• dvidir: DVI documentation
• pdfdir: PDF documentation
• psdir: PS documentation
• destdir: Prepend a path when installing package
• findlib_version
• is_native
• suffix_program
• rm: Remove a file.
• rmdir: Remove a directory.
• debug: Compile with ocaml debug flag on.
• profile: Compile with ocaml profile flag on.
• ocamlbuildflags: OCamlbuild additional flags

Other variables are defined depending on your _oasis file:

• Variables from BuildDepends: pkg_ and the name of the findlib package. It points to the directory containing the package. If there is a version constraint, it is also translated to a variable. It contains a boolean value to know if the version is ok or not. Internal findlib packages don't create variables. Example: BuildDepends: oUnit (>= 1.0.3) becomes two variables pkg_oUnit = /usr/lib/ocaml/ounit and pkg_oUnit_ge_1_0_3 = true.
• Variables from external BuildTools: the variable is the name given in the field and its value the filename of the executable. Example: BuildTools: make becomes make = /usr/bin/make.
• Dynamic variables from internal BuildTools: the variable is the name of the Executable section and its value the filename of the executable. Example: Executable ocamlmod becomes ocamlmod = _build/src/tools/ocamlmod. These variables are set through setup.log rather than setup.data. They are set only when the corresponding files is built.

It is also possible to apply transformation through functions. This is useful when you need to use properties that need to be determined at runtime:

• utoh: convert an Unix filename into a host filename (e.g. UNIX -> Win32 conversion).
• ocaml_escaped: call to String.escaped.

For example $(utoh src/test.ml) will be replaced by src\test.ml on Windows.

Customization of generated files

When OASIS generates file, it always replace only lines between OASIS_START and OASIS_STOP. These keywords are commented and followed by data to check that content is unchanged.

If the file doesn't exist, OASIS will create the whole file using default header and footer.

If OASIS detects a change inside the section being replaced, it will create a backup of the file and issue a warning.

Customization of setup.ml

setup.ml as any generated files can be customized in its header and footer. Moreover it can be customized through hook in the code directly.

TODO: explains hook.

Using OASIS during software development

Since _oasis becomes a central place of information about the building process, it can be quite cumbersome to run again and again oasis. You can avoid it using the -dev flags when calling oasis for the first time. This way it will rebuilt very dependents build files each time you call ocaml setup.ml. A setup.ml built this way, should not be distributed. This intended for development purpose only.

Plugins

OASIS is basically built around plugins. They are used to define specific behavior for generating files and including their own code in setup.ml.

There are 6 categories of plugin:

• Conf: apply to configure step, used in the field ConfType
• Build: apply to build stepi, used in the field BuildType
• Test: apply to test sections, used in the field Type of a test
• Doc: apply to documentation sections, used in the field Type of a document
• Install: apply to install and uninstall steps, used in the field DocType
• Extra: everything else, used in the field Plugins

ocaml setup.ml -configure

This is the first step to perform. It is mandatory. It runs various test of the build environment to check that everything required is installed.

ocaml setup.ml -build

This step is mandatory. Build libraries and executables.

ocaml setup.ml -test

This step is optional. Run defined test. Need the build step before.

ocaml setup.ml -doc

This step is optional. It builds API documentation for library and extra documentation as defined in Document.

ocaml setup.ml -install

This step is mandatory. Install what has been built in build and doc step. Also install data files as defined in DataFiles fields.

ocaml setup.ml -uninstall

This step is optional. Remove files and libraries installed.

ocaml setup.ml -reinstall

This step is optional. Perform an uninstall and then an install step.

ocaml setup.ml -clean

This step is optional. Clean generated files during build and doc steps.

ocaml setup.ml -distclean

This step is optional. Try to go back to pristine source state.

ocaml setup.ml -all

This step is optional. Run configure, build, test and doc step in one run.

Command line

OASIS (C) 2009-2010 OCamlCore SARL

oasis [global-options] subcommand [subcommand-options]

Global options:

This program allows to manipulate OASIS enabled package, i.e. package that contains an _oasis file. It is made of several subcommands that provide features around this file. Some subcommands require the installation of third party plugins.

You need to specify a subcommand as defined in the following above.

-C dir

Change directory before running.

-quiet

Run quietly

-debug

Output debug message

-help|--help

Display this list of options

Available subcommands:

check

Check an _oasis file

help

Display help for a subcommand

manual

Display user manual

query

Query an _oasis file

quickstart

Launch an helper to write _oasis file

setup

Translate _oasis into a build system

setup-clean

Clean all template files from their content

setup-dev

Translate _oasis into a build system that auto-update

Subcommand check

This subcommand load an _oasis file and apply standard checks.

Usage: oasis [global-options] check [options]

Options:

-ignore-plugins

Ignore plugin's field.

-oasis fn

_oasis file to use.

Subcommand help

This subcommand display help of other subcommands or of all subcommands.

Usage: oasis [global-options*] help [subcommand|all]

Subcommand manual

This subcommand print the manual of OASIS. It uses the markdown syntax to print it and more precisely the pandoc extension of this syntax.

This manual describes the command line tool oasis, the _oasis file format and the generated setup.ml file.

Usage: oasis [global-options*] manual

Options:

-o fn

Output manual to filename.

Subcommand query

This subcommand load an _oasis file and search its content for information.

The query string follow this convention:

• ListSections: return all the section found
• ListFields: return all the fields, it recurses through sections
• field: search for this field in the toplevel
• section.field: search for this field in the section

Query examples:

• version: return the version
• executable("test").install: return the field "install" of the executable "test".

You can use multiple queries, they will be executed in order.

Usage: oasis [global-options] query [options] query*

Options:

-separator str

String to add between answers.

-oasis fn

_oasis file to use.

-ignore-plugins

Ignore plugin's field.

Subcommand quickstart

This subcommand is an helper to write _oasis file. It asks a serie of questions to create an initial _oasis file. The questions depend on the level of the user, you can set this level with the -level command line option.

At the end of the process, you have the possibility to edit, to display or to write the generated file.

Usage: oasis [global-options] quickstart [options]

Options:

-level {beginner|intermediate|expert}

Quickstart level, skip questions according to this level.

-machine

Computer readable questions for automatic completion.

-real-oasis

Use the real 'oasis' executable filename when generating developper mode setup.ml.

-run

Run a command after generating files, this is the mode used by setup.ml in developper mode. Don't use it directly.

-only-setup

When generating the build system, keep only setup.ml and delete other generated files.

-oasis fn

_oasis file to use.

Subcommand setup

This is the main subcommand of oasis, it compiles the _oasis file into a self contained setup.ml. The generated file handle the various step to configure, build and install your project.

Usage: oasis [global-options*] setup

Options:

-oasis fn

_oasis file to use.

Subcommand setup-clean

This subcommand go through every generated files and remove the replaceable part in it. It also tries to clean backup files made by a failed SetupDev subcommand invocation.

The replaceable part of a generated file is everything between OASIS_START and OASIS_STOP.

Usage: oasis [global-options] setup-clean [options]

Options:

-replace-sections Empty

replace section in generated files (i.e. remove content between OASIS_START and OASIS_STOP).

Subcommand setup-dev

This subcommand is the developper counterpart of the Setup subcommand. It acts the same way but it produces a setup.ml that still requires the executable oasis in order to recompile the _oasis file at each invocation.

The big advantage to create a setup.ml this way is that you don't have to call oasis setup each time you update the _oasis file. The other advantage is that it keeps clean your build system, i.e. it generates a file, use it and reset it to its pristine state, which helps to maintain the changes in this file to the bare minimum.

This subcommand is suited for developpers, but you should use the Setup subcommand when you want to distribute your work.

Usage: oasis [global-options] setup-dev [options]

Options:

-real-oasis

Use the real 'oasis' executable filename when generating developper mode setup.ml.

-run

Run a command after generating files, this is the mode used by setup.ml in developper mode. Don't use it directly.

-only-setup

When generating the build system, keep only setup.ml and delete other generated files.

-oasis fn

_oasis file to use.