OASIS is a tool to integrate a configure, build and install system in your OCaml project. It helps to create standard entry points in your build system and allows external tools to analyse your project easily. It is the building brick of
OASIS-DB, a CPAN for OCaml.
This release takes almost 18 months to complete. This is too long and I will talk in another blog post on the way I am trying to improve this right now (esp. using continuous integration).
This new release fixes a small bug (1 line) that prevents
setup.ml to run with OCaml 4.00. If you have projects that was generated with a former release consider upgrading to OASIS 0.3.0.
There are several big new stuff that comes with this release. It now supports
Pack: field for libraries which allows to pack your library using
-for-pack and so on.
We are also compiling
.cmxs (dynlink object for native) by default and we publish them in the
META file. This feature was implemented in order to get more libraries to provide .cmxs and to help project like
Ocsigen to take advantage of this. If you want to get rid of this at configure time, you can use
./configure --override native_dynlink false.
We introduce two new default flags:
--enable-tests and
--disable-docs for configure. These are implicit flags that define if we will run
Test sections or compile
Document sections. They are especially useful to reduce the number of dependencies, because dependencies of
Test will be excluded by default. We recommend to set
Build$: flag(tests) to any
Library or
Executable sections that are only useful for tests. This allows you to really cut down the number of dependencies.
The last change I want to introduce is about the old
setup-dev subcommand which is now deprecated. It has been replaced by 2 different update schemes. I am pretty excited by this feature which in fact comes from OASIS user (esp.
Lwt project). The former scheme was to have a big 'setup.ml' that always call the command
oasis to update. This was complex and not very useful. We now have 2 mode:
dynamic and
weak.
dynamic allow you to have a small
setup.ml and to keep your VCS history clean but you need to install OASIS.
weak need a big
setup.ml but only need to call the command
oasis if someone change something in
_oasis. This mode is targeted to project that wants to be able to checkout from VCS an OCaml project without installing OASIS. The difference generated by
weak mode doesn't pollute too much the VCS history because most the time they make sense. For example, you upgrade your package version number in
_oasis and it produces a change with 6 lines where the version number changes in every
META,
setup.ml files and so on.
This version has been tested on:
- Linux (Debian Sid and Debian Squeeze with GODI, OCaml 3.12)
- Windows Vista with MS Visual Studio 2008 toolchain, OCaml 3.12
- Mac OS X, OCaml 3.12 from GODI
You can download it
here or use your favorite package manager:
Debian (UPDATE: pending upload)
$ apt-get install -t experimental oasis
GODI
$ godi_console perform -build apps-oasis
odb.ml
$ ocaml odb.ml oasis
Here is the complete changelog:
EXTREMLY IMPORTANT changes (read this)
- Fix bug with
scanf %S@\n for ocaml 4.00. We were unfortunetaly using an undocumented tolerance of Scanf in the previous version. You should consider making new release using this version that fixed this.
PACKAGES uploaded to oasis-db will be automatically "derived" before OCaml 4.00 release (i.e. oUnit v1.1.1 will be regenerated with this new version as oUnit v1.1.1~oasis1).
PACKAGES not uploaded to oasis-db need to be regenerated. In order not to break 3rd party tools that consider a tarball constant, I recommend to create a new version.
Thanks to INRIA OCaml team for synchronizing with us on this point.
Major changes:
- Handle the field
Pack: true to be able to create packed libraries. It also installs .mli files for documentation into the target directory. The pack option is only supported for OASISFormat: 0.3, you will need to update the version of your _oasis file to match it.
- Introduce --enable-tests to disable tests and docs at oasis level. It seems a very common pattern to have a
Flag tests to turn off by default the tests. This is now define as a standard var and you should remove you previous Flag tests but you can continue to use flag(tests) where needed.
You can now have the following example:
...
Executable test_exec
Install: false
Build$: flag(tests)
MainIs: testExec.ml
BuildDepends: oUnit
Test main
Command: $test_exec
TestTools: test_exec
...
The
Run$: flag(tests) is implicit for the section
Test main. The default value is
false for tests. If all the executable for test are flagged correctly (
Build$: flag(tests)), you'll get rid of the dependency on oUnit.
It works the same for documentation, however the default is
true. (Closes: #866)
- Allow to define interdependent flags
In order to allow interdependent flags, we transform back lazy values into
unit -> string functions. This allows to change a flag value on the command line and to update all the dependent values. (Closes: #827, #938)
- Deprecate the subcommand oasis setup-dev in favor of oasis setup -setup-update none weak dynamic
It defines different ways to manage the auto-update of setup.ml:
- none: this is the default mode, and the one you should use when distributing tarballs. No update are performed at al.
- weak: the update is only triggered when something change in _oasis , we keep all files generated
- dynamic: the content of 'setup.ml' is ultra small (<2kB) and we only keep a small setup.ml, Makefile and configure.
The choice between
weak and
dynamic depends on your need with regard to VCS and to the presence of
oasis. The
weak allow to checkout the project from VCS and be able to work on it, without the need of installing 'oasis' as long as you don't change the file
_oasis. But it clutter your VCS history with changes to the build system each time you change something in
_oasis. The 'dynamic' mode gives you no VCS history pollution but makes mandatory to have installed oasis libraries.
- Don't copy executable in ocamlbuild
Avoid copying executable to their real name. It helps to call ocamlbuild a single time for the whole build rather than calling it n time (n = number of executable sections) and copying resulting exec.
This speeds up the build process because ocamlbuild doesn't have to compute/scan dependencies each time.
The drawback is that you have to use
$foo when you want to call
Executable foo, because
$foo will be '_build/.../main.byte'.
- Change the way we parse command line like option (
CCOpt, CCLib and the like). We have implemented a real POSIX command line parser, except that variables are processed by Buffer.add_substitute (except if correctly escaped, using Buffer.add_substitute escaping).
For example:
CCOpt: -DEXTERNAL_EXP10 -L/sw/lib "-framework vecLib"
Will be parsed correctly and outputed according to target OS.
- Minimize the dependencies of the project.
In order to ease building oasis, we have minimize the number of dependencies. You only need to install
ocamlmod,
ocamlify and
ocaml-data-notation for a standard build without tests. Dependencies on
pcre,
extlib and
ocamlgraph has been dropped. The remaining dependencies are hidden behind a flag
tests.
- Implement proposal for handling plugin in META, using "plugin" extra directives
OASIS now produces .cmxs file by default and add them to
META.
Now a
META looks like:
...
archive(byte) = "oasis.cma"
archive(byte, plugin) = "oasis.cma"
archive(native) = "oasis.cmxa"
archive(native, plugin) = "oasis.cmxs"
...
This will ultimately help to generate automatically
.cmxs for all oasis enabled projects. We hope that this new feature will improve dynamic linking use in OCaml (esp. for project like Ocsigen).
Other changes
- Produce only subcommands specific helps when asked (Closes: #783)
- Use pager for long textual output (Closes: #782)
- Give the help summary directly when running just "oasis" (Closes: #781)
- Remove pwd filename prefix to avoid too long command line on Windows (Closes: #1007)
- Install required .cmx when installing libraries (Closes: #686, #885)
- Retain blanks at the beginning of line in freeform (Closes: #811)
- Allow
PreConfCommand to create setup.data with any variables inside (Closes: #823)
- Allow to use setup.data in shell script and Makefile (Closes: #982)
- Fix execute permissions (Closes: #980)
- Drop extra version in ocaml version (Closes: #964, #888)
- Always output info messages on stderr (Closes: #785)
- Fix interversion in version comparator lexer (Closes: #808)
- Document the fact that setup.data is mandatory (Closes: #946)
- configure translates getopt command line to Arg (Closes: #778, #804)
- Generate valid META when there are line breaks in synopsis (Closes: #933)
- Keep owner of generated files (Closes: #793)
- Set -I +threads for ocamlfind ocamldoc in ocamlbuild (Closes: #949)
- Exclude VCS directories by default (Closes: #847)
- Print the configure summary in the "normal" order.
- Merge findlib virtual containers with the same name
- Synchronize plugin data for section
- Improve documentation
- Verify validity of input when parsing in quickstart (Closes: #797)
- Fix stack overflow when there are twice the same library (Closes: #1130)
- Parse license examples for DEP5 specification (Closes: #1102)
- Be ultra-liberal regarding version syntax (allow '_' and ' ' in the version).
- Allow to add extra content to META files (XMETAExtraLines)
- Allow to use executable name that contains "-" as a variable (replacing "-" by "_").
Thanks to Anil Madhavapeddy, Pierre Chambart, Christophe Troestler, Jeremie Dimino, Ronan Le Hy, Yaron Minsky and Till Varoquaux for their help with this release.
Also thanks to all the testers of the numerous release candidates. This was a long work and each time a tester has downloaded oasis has helped me to know that I was working for someone.