2018-01-26 07:26:00 +00:00
|
|
|
Dune (Jbuilder) - A composable build system
|
|
|
|
===========================================
|
|
|
|
|
|
|
|
__Jbuilder has been renamed to Dune__. A full renaming of the documentation and
|
|
|
|
the tool will be done as part of the 1.0 release.
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-04-20 15:52:05 +00:00
|
|
|
Jbuilder is a build system designed for OCaml/Reason projects only. It
|
2017-02-28 17:20:41 +00:00
|
|
|
focuses on providing the user with a consistent experience and takes
|
|
|
|
care of most of the low-level details of OCaml compilation. All you
|
|
|
|
have to do is provide a description of your project and Jbuilder will
|
|
|
|
do the rest.
|
|
|
|
|
|
|
|
The scheme it implements is inspired from the one used inside Jane
|
|
|
|
Street and adapted to the open source world. It has matured over a
|
2017-08-06 09:39:42 +00:00
|
|
|
long time and is used daily by hundreds of developers, which means
|
2017-02-28 17:20:41 +00:00
|
|
|
that it is highly tested and productive.
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
Jbuilder comes with a [manual][manual]. If you want to get started
|
2017-11-26 19:12:23 +00:00
|
|
|
without reading too much, you can look at the [quick start
|
|
|
|
guide][quick-start] or watch [this introduction video][video].
|
2017-02-21 15:09:26 +00:00
|
|
|
|
2017-06-13 16:07:36 +00:00
|
|
|
The [example][example] directory contains examples of projects using
|
2017-06-02 12:47:07 +00:00
|
|
|
jbuilder.
|
2017-03-21 14:37:35 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
[![Travis status][travis-img]][travis] [![AppVeyor status][appveyor-img]][appveyor]
|
2017-03-01 09:04:01 +00:00
|
|
|
|
2017-07-14 11:19:55 +00:00
|
|
|
[manual]: https://jbuilder.readthedocs.io/en/latest/
|
|
|
|
[quick-start]: https://jbuilder.readthedocs.io/en/latest/quick-start.html
|
2018-01-23 09:52:44 +00:00
|
|
|
[example]: https://github.com/ocaml/dune/tree/master/example
|
2018-01-23 05:23:19 +00:00
|
|
|
[travis]: https://travis-ci.org/ocaml/dune
|
|
|
|
[travis-img]: https://travis-ci.org/ocaml/dune.svg?branch=master
|
2018-01-23 05:22:32 +00:00
|
|
|
[appveyor]: https://ci.appveyor.com/project/diml/dune/branch/master
|
2018-01-23 05:21:42 +00:00
|
|
|
[appveyor-img]: https://ci.appveyor.com/api/projects/status/rsxayce22e8f2jkp?svg=true
|
2017-06-02 12:47:07 +00:00
|
|
|
[merlin]: https://github.com/ocaml/merlin
|
|
|
|
[opam]: https://opam.ocaml.org
|
|
|
|
[jenga]: https://github.com/janestreet/jenga
|
2018-01-23 09:52:44 +00:00
|
|
|
[issues]: https://github.com/ocaml/dune/issues
|
2017-06-02 12:47:07 +00:00
|
|
|
[topkg-jbuilder]: https://github.com/diml/topkg-jbuilder
|
2017-11-26 19:12:23 +00:00
|
|
|
[video]: https://youtu.be/BNZhmMAJarw
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
Overview
|
|
|
|
--------
|
|
|
|
|
|
|
|
Jbuilder reads project metadata from `jbuild` files, which are either
|
2017-02-28 17:20:41 +00:00
|
|
|
static files in a simple S-expression syntax or OCaml scripts. It uses
|
|
|
|
this information to setup build rules, generate configuration files
|
2017-06-02 12:47:07 +00:00
|
|
|
for development tools such as [merlin][merlin], handle installation,
|
|
|
|
etc...
|
2017-02-28 17:20:41 +00:00
|
|
|
|
2017-03-28 00:05:59 +00:00
|
|
|
Jbuilder itself is fast, has very low overhead and supports parallel
|
2017-02-28 17:20:41 +00:00
|
|
|
builds on all platforms. It has no system dependencies: all you need
|
|
|
|
to build jbuilder and packages using jbuilder is OCaml. You don't need
|
2017-06-02 12:47:07 +00:00
|
|
|
`make` or `bash` as long as the packages themselves don't use `bash`
|
2017-03-28 00:05:59 +00:00
|
|
|
explicitly.
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-04-24 11:58:11 +00:00
|
|
|
Especially, one can install OCaml on Windows with a binary installer
|
|
|
|
and then use only the Windows Console to build Jbuilder and packages
|
|
|
|
using Jbuilder.
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
Strengths
|
|
|
|
---------
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
### Composable
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-02-28 17:20:41 +00:00
|
|
|
Take n repositories that use Jbuilder, arrange them in any way on the
|
|
|
|
file system and the result is still a single repository that Jbuilder
|
|
|
|
knows how to build at once.
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-02-28 17:20:41 +00:00
|
|
|
This make simultaneous development on multiple packages trivial.
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
### Gracefully handles multi-package repositories
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-02-28 17:20:41 +00:00
|
|
|
Jbuilder knows how to handle repositories containing several
|
2017-06-02 12:47:07 +00:00
|
|
|
packages. When building via [opam][opam], it is able to correctly use
|
2017-02-28 17:20:41 +00:00
|
|
|
libraries that were previously installed even if they are already
|
|
|
|
present in the source tree.
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-03-02 18:21:19 +00:00
|
|
|
The magic invocation is:
|
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
```sh
|
2017-03-02 18:21:19 +00:00
|
|
|
$ jbuilder build --only-packages <package-name> @install
|
2017-06-02 12:47:07 +00:00
|
|
|
```
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
### Building against several configurations at once
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-02-28 17:20:41 +00:00
|
|
|
Jbuilder is able to build a given source code repository against
|
|
|
|
several configurations simultaneously. This helps maintaining packages
|
|
|
|
across several versions of OCaml as you can tests them all at once
|
|
|
|
without hassle.
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-02-28 17:20:41 +00:00
|
|
|
This feature should make cross-compilation easy, see details in the
|
2017-06-02 12:55:11 +00:00
|
|
|
[roadmap](ROADMAP.md).
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
This feature requires [opam][opam].
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
### Jenga bridge
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
[Jenga][jenga] is another build system for OCaml that has more
|
|
|
|
advanced features such as polling or much better editor
|
|
|
|
integration. Jenga is more powerful and more complex and as a result
|
2017-06-30 21:33:37 +00:00
|
|
|
has many more dependencies. It is planned to implement a small bridge
|
2017-06-02 12:47:07 +00:00
|
|
|
between the two so that a Jbuilder project can build with Jenga using
|
|
|
|
this bridge.
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
Requirements
|
|
|
|
------------
|
2017-04-21 16:34:34 +00:00
|
|
|
|
|
|
|
Jbuilder requires OCaml version 4.02.3 or greater.
|
|
|
|
|
2017-06-05 15:32:58 +00:00
|
|
|
installation
|
|
|
|
------------
|
2017-04-21 16:34:34 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
The recommended way to install jbuilder is via the
|
|
|
|
[opam package manager][opam]:
|
2017-04-21 16:34:34 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
```sh
|
2017-04-21 16:34:34 +00:00
|
|
|
$ opam install jbuilder
|
2017-06-02 12:47:07 +00:00
|
|
|
```
|
2017-04-21 16:34:34 +00:00
|
|
|
|
|
|
|
You can also build it manually with:
|
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
```sh
|
2017-07-18 09:17:53 +00:00
|
|
|
$ make release
|
2017-04-21 16:34:34 +00:00
|
|
|
$ make install
|
2017-06-02 12:47:07 +00:00
|
|
|
```
|
2017-04-21 16:34:34 +00:00
|
|
|
|
2017-07-18 09:17:53 +00:00
|
|
|
Note however that `make install` requires the `opam-installer`
|
|
|
|
tool. Running simply `make` will build jbuilder using the development
|
|
|
|
settings.
|
2017-04-21 16:34:34 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
If you do not have `make`, you can do the following:
|
2017-04-21 16:34:34 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
```sh
|
2017-04-21 16:34:34 +00:00
|
|
|
$ ocaml bootstrap.ml
|
|
|
|
$ ./boot.exe
|
|
|
|
$ ./_build/default/bin/main.exe install
|
2017-06-02 12:47:07 +00:00
|
|
|
```
|
2017-04-21 16:34:34 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
Support
|
|
|
|
-------
|
2017-04-21 16:34:34 +00:00
|
|
|
|
|
|
|
If you have questions about jbuilder, you can send an email to
|
2017-06-02 12:47:07 +00:00
|
|
|
ocaml-core@googlegroups.com or [open a ticket on github][issues].
|
2017-04-21 16:34:34 +00:00
|
|
|
|
2017-06-02 12:47:07 +00:00
|
|
|
Status
|
|
|
|
------
|
2016-12-02 13:54:32 +00:00
|
|
|
|
2018-03-20 20:28:36 +00:00
|
|
|
Dune is now fairly stable and is used by the majority of packages on
|
|
|
|
opam. The package is still in beta version as we are waiting for the
|
|
|
|
renaming from Jbuilder to Dune before releasing version 1.0.0. Note
|
|
|
|
that Dune will have backward compatiblity with Jbuilder, in particular
|
|
|
|
existing Jbuilder projects will continue to be buildable with
|
|
|
|
Dune. Additionally, Dune will be able to automatically convert a
|
|
|
|
Jbuilder project into a Dune project.
|