122 lines
4.1 KiB
Org Mode
122 lines
4.1 KiB
Org Mode
|
* A fast, portable and opinionated build system
|
||
|
|
|
||
|
|
Jbuilder is a build system that was designed to simplify the release
|
||
|
|
of Jane Street packages. It should however cover the needs of a wide
|
||
|
|
range of OCaml packages. It reads metadata from \"jbuild\" files
|
||
|
|
following a very simple s-expression syntax.
|
||
|
|
|
||
|
|
** Overview
|
||
|
|
|
||
|
|
Jbuilder is fast, has very low-overhead and supports parallel 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
|
||
|
|
=make= or =bash= as long as the packages themselves don't use =bash=
|
||
|
|
explicitely.
|
||
|
|
|
||
|
|
This hasn't been tested yet, but in theory one should be able to
|
||
|
|
install OCaml on Windows with a binary installer and then use only the
|
||
|
|
Windows Console to build Jbuilder and packages using Jbuilder.
|
||
|
|
|
||
|
|
** Features
|
||
|
|
|
||
|
|
*** Multi-package development
|
||
|
|
|
||
|
|
Jbuilder supports multi-package development by simply dropping
|
||
|
|
multiple repositories into the same directory. You just need to create
|
||
|
|
an empty file =jbuild-workspace= to mark the root of your workspace.
|
||
|
|
|
||
|
|
*** Multi-context builds
|
||
|
|
|
||
|
|
Jbuilders supports multi-context builds, such as building against
|
||
|
|
several opam roots/switches simultaneously. This helps maintaining
|
||
|
|
packages across several versions of OCaml and gives cross-compilation
|
||
|
|
for free; when you need a program to run on the host, you simply use
|
||
|
|
the one from the corresponding host context.
|
||
|
|
|
||
|
|
*** Defining several packages in one repository
|
||
|
|
|
||
|
|
Jbuilder supports building several packages from the same
|
||
|
|
repository. When building via opam, it is able to correctly use
|
||
|
|
already installed libraries instead of the one present in the tarball.
|
||
|
|
|
||
|
|
The magic invocation is =jbuilder build-package <package>= which starts
|
||
|
|
by filtering out everything that is part of another opam package.
|
||
|
|
|
||
|
|
*** Develop with jenga, release with jbuilder
|
||
|
|
|
||
|
|
Jbuilder is intended as a fast release build system. Eventually we'll
|
||
|
|
have jenga rules that are able to understand the jbuilder rules. This
|
||
|
|
means that one will be able to use jenga as a confortable development
|
||
|
|
build system that knows how to do polling builds or talk to emacs
|
||
|
|
and use jbuilder to release packages with as few requirements as
|
||
|
|
possible.
|
||
|
|
|
||
|
|
** Status
|
||
|
|
|
||
|
|
Jbuilder is still in its infancy and in active development. One vital
|
||
|
|
thing that is still missing is a proper CLI. It is planned to add one
|
||
|
|
by dropping a copy of [[http://erratique.ch/software/cmdliner][cmdliner]]
|
||
|
|
inside jbuilder.
|
||
|
|
|
||
|
|
Most of the core functionality is already there however. What you can do
|
||
|
|
right now is write some jbuild files, and invoke jbuilder at the root
|
||
|
|
of your project as follows:
|
||
|
|
|
||
|
|
#+begin_src
|
||
|
|
$ jbuilder <package>.install
|
||
|
|
#+end_src
|
||
|
|
|
||
|
|
Building the =.install= file will build all the things that need to be
|
||
|
|
installed.
|
||
|
|
|
||
|
|
** Roadmap
|
||
|
|
|
||
|
|
Following is the current plan for the future of jbuild.
|
||
|
|
|
||
|
|
*** CLI
|
||
|
|
|
||
|
|
Add a proper [[http://erratique.ch/software/cmdliner][cmdliner]] based CLI.
|
||
|
|
Jbuilder will include a copy of cmdliner to avoid the extra dependency.
|
||
|
|
|
||
|
|
*** Documentation
|
||
|
|
|
||
|
|
Document the usage and design of Jbuilder.
|
||
|
|
|
||
|
|
*** Stable jbuild types
|
||
|
|
|
||
|
|
Add a stable version of the jbuild format so that one can write
|
||
|
|
=(jbuild_format 1)= inside jbuild files and be sure that they will
|
||
|
|
work with future versions of jbuild.
|
||
|
|
|
||
|
|
The standard jbuild format will evolve with the format used inside
|
||
|
|
Jane Street so that it can be used to easily build Jane Street packages.
|
||
|
|
|
||
|
|
*** Finding the project/workspace root
|
||
|
|
|
||
|
|
Currently =jbuilder= assumes that the root of the project/workspace is
|
||
|
|
where it is started. Eventually this will be changed as follows:
|
||
|
|
|
||
|
|
- if there is a =jbuild-workspace= in a parent directory, it marks the root;
|
||
|
|
- if not found, look for a =opam= or =package.opam= file in parent directories;
|
||
|
|
- if not found, look for a =.git=, =.hg=, ... file in parent directories;
|
||
|
|
- if not found, use the current directory as root.
|
||
|
|
|
||
|
|
*** Cross-compilation
|
||
|
|
|
||
|
|
Everything needed for cross-compilation is implemented. One
|
||
|
|
essentially need to add a function =host_exe : Path.t -> Path.t=
|
||
|
|
inside build contexts to make it all work, as well as a way to define
|
||
|
|
the build contexts. These could be defined inside =jbuild-workspace=
|
||
|
|
as follows:
|
||
|
|
|
||
|
|
#+begin_src scheme
|
||
|
|
(context
|
||
|
|
((name foo)
|
||
|
|
(switch 4.04.0)))
|
||
|
|
|
||
|
|
(context
|
||
|
|
((name foo+mingw)
|
||
|
|
(switch 4.04.0+mingw)
|
||
|
|
(host foo)))
|
||
|
|
#+end_src
|