OASIS 0.3.0 release

Logo OASIS small 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_console perform -build apps-oasis


$ 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.


1. On Thursday, August 23 2012, 17:20 by Yong


I wonder if you could provide a binary package for oasis 0.3 on your website (just like you did for v0.2)? The reason is I run into a dependency loop while trying to build the ocaml-core library:

The ocaml-core library requires oasis 0.3, which requires odn to build, which in turn requires type_conv, which is now part of ocaml-core!

So basically I can't install ocaml-core unless I have a binary version of oasis 0.3 or a previously installed type_conv library (which I don't have).



They posted on the same topic

Trackback URL : http://sylvain.le-gall.net/blog/index.php?trackback/72

This post's comments feed