[Caml-list] [ANN] Jbuilder 1.0+beta1

[Caml-list] [ANN] Jbuilder 1.0+beta1

[Jeremie Dimino]

Hi,

I'm pleased to annouce the 1.0+beta1 release of Jbuilder.

Jbuilder is a build system targetting OCaml projects and opam. It uses
the same model as what is used at Jane Street: users write simple
"jbuild" files to describe their libraries and executables and
Jbuilder takes care of the rest. You don't need to know much about
OCaml compilation to use Jbuilder.

Jbuilder comes with a manual [1] and a quick start guide [2] showing
common patterns.

Jbuilder can be installed via opam:

    $ opam install jbuilder
    $ less `opam config var doc`/jbuilder/manual.org

Jbuilder is developed primarily on github [3] and contributions are
welcome.

Interesting features
====================

I think it is worth mentioning the following features of Jbuilder,
that should make the everyday life of an OCaml hacker easier:

jbuilder exec <command>
-----------------------

This will run <command> in an environment where it has access to the
binaries, libraries, manual pages, ... previously built and that are
to be installed. This is convenient for testing things in the toplevel
before installing them for instance.

jbuilder external-lib-deps --missing <targets>
----------------------------------------------

This will list all the external library dependencies required to build
<targets>, so that you have to run only one "opam install" command
instead of installing dependencies one by one until the build succeed.

building against several versions of OCaml at once
--------------------------------------------------

This is useful for locally testing that a project builds against all
supported versions of OCaml:

    $ cat > jbuild-workspace <<EOF
    (context ((switch 4.02.3)))
    (context ((switch 4.03.0)))
    (context ((switch 4.04.0)))
    (context ((switch 4.05.0+beta2)))
    (context ((switch 4.06.0+trunk)))
    EOF
    $ jbuilder build @install @runtest

I find it convenient to add a jbuild-workspace.dev file at the root of
a project with the following rule in the Makefile:

    all-supported-ocaml-versions:
        jbuilder build @install @runtest --workspace jbuild-workspace.dev

building multiple projects at once
----------------------------------

This is great for working on several related projects:

    $ opam source base
    [...]
    $ opam source stdio
    [...]
    $ jbuild build @install

This method has been successfully tested to build the ~100 Jane Street
packages at once.

Changes
=======

Here is the full set of changes since the first alpha release:

- Added a manual

- Support incremental compilation

- Switched the CLI to cmdliner and added a =build= command
  (#5, Rudi Grinberg)

- Added a few commands:
  + =runtest=
  + =install=
  + =uninstall=
  + =installed-libraries=
  + =exec=: execute a command in an environment similar to what you
    would get after =jbuilder install=

- Removed the =build-package= command in favor of a =--only-packages=
  option that is common to all commands

- Automatically generate =.merlin= files
  (#2, Richard Davison)

- Improve the output of jbuilder, in particular don't mangle the
  output of commands when using =-j N= with =N > 1=

- Generate a log in =_build/log=

- Versioned the jbuild format and added a first stable version.
  You should now put =(jbuilder_version 1)= in a =jbuild= file at the
  root of your project to ensure forward compatibility

- Switch from =ppx_driver= to =ocaml-migrate-parsetree.driver=. In
  order to use ppx rewriters with Jbuilder, they need to use
  =ocaml-migrate-parsetree.driver=

- Added support for aliases
  (#7, Rudi Grinberg)

- Added support for compiling against multiple opam switch
  simultaneously by writing a =jbuild-worspace= file

- Added support for OCaml 4.02.3

- Added support for architectures that don't have natdynlink

- Search the root according to the rules described in the manual
  instead of always using the current directory

- extended the action language to support common actions without using
  a shell:
  + =(with-stdout-to <file> <DSL>)=
  + =(copy <src> <dst>)=
  ...

- Removed all implicit uses of bash or the system shell. Now one has
  to write explicitely =(bash "...")= or =(system "...")=

- Generate meaningful versions in =META= files

- Strengthen the scope of a package. Jbuilder knows about package
  =foo= only in the sub-tree starting from where =foo.opam= lives

Notes
=====

Jbuilder was released in opam today, and since then I got reports that
it often chooses the wrong "root". The rules for finding the root of
the current workspace will have to be changed for the 1.0 release. In
the meantime, you can force the compilation root by writing a
jbuild-workspace containing "(context default)" where you want the
root to be.


[1] https://github.com/janestreet/jbuilder/blob/master/doc/manual.org
[2] https://github.com/janestreet/jbuilder/blob/master/doc/quick-start.org
[3] https://github.com/janestreet/jbuilder

-- 
Jeremie Dimino

Re: [Caml-list] [ANN] Jbuilder 1.0+beta1

[Jeremie Dimino]

I just  released a beta2 with better rules for finding the workspace
root [1]. In beta1, jbuilder would often choose the home directory as
root, causing it to scan the whole home directory.

Following is the full changelog:

- Simplified the rules for finding the root of the workspace as the
  old ones were often picking up the home directory. New rules are:
  + look for a =jbuild-workspace= file in parent directories
  + look for a =jbuild-workspace*= file in parent directories
  + use the current directory

- Fixed the expansion of =${ROOT}= in actions

- Install =quick-start.org= in the documentation directory

- Add a few more things in the log file to help debugging

[1] https://github.com/janestreet/jbuilder/blob/master/doc/manual.org#finding-the-root

On Wed, Mar 8, 2017 at 5:53 PM, Jeremie Dimino <jdimino@janestreet.com> wrote:
> Hi,
>
> I'm pleased to annouce the 1.0+beta1 release of Jbuilder.
>
> Jbuilder is a build system targetting OCaml projects and opam. It uses
> the same model as what is used at Jane Street: users write simple
> "jbuild" files to describe their libraries and executables and
> Jbuilder takes care of the rest. You don't need to know much about
> OCaml compilation to use Jbuilder.
>
> Jbuilder comes with a manual [1] and a quick start guide [2] showing
> common patterns.
>
> Jbuilder can be installed via opam:
>
>     $ opam install jbuilder
>     $ less `opam config var doc`/jbuilder/manual.org
>
> Jbuilder is developed primarily on github [3] and contributions are
> welcome.
>
> Interesting features
> ====================
>
> I think it is worth mentioning the following features of Jbuilder,
> that should make the everyday life of an OCaml hacker easier:
>
> jbuilder exec <command>
> -----------------------
>
> This will run <command> in an environment where it has access to the
> binaries, libraries, manual pages, ... previously built and that are
> to be installed. This is convenient for testing things in the toplevel
> before installing them for instance.
>
> jbuilder external-lib-deps --missing <targets>
> ----------------------------------------------
>
> This will list all the external library dependencies required to build
> <targets>, so that you have to run only one "opam install" command
> instead of installing dependencies one by one until the build succeed.
>
> building against several versions of OCaml at once
> --------------------------------------------------
>
> This is useful for locally testing that a project builds against all
> supported versions of OCaml:
>
>     $ cat > jbuild-workspace <<EOF
>     (context ((switch 4.02.3)))
>     (context ((switch 4.03.0)))
>     (context ((switch 4.04.0)))
>     (context ((switch 4.05.0+beta2)))
>     (context ((switch 4.06.0+trunk)))
>     EOF
>     $ jbuilder build @install @runtest
>
> I find it convenient to add a jbuild-workspace.dev file at the root of
> a project with the following rule in the Makefile:
>
>     all-supported-ocaml-versions:
>         jbuilder build @install @runtest --workspace jbuild-workspace.dev
>
> building multiple projects at once
> ----------------------------------
>
> This is great for working on several related projects:
>
>     $ opam source base
>     [...]
>     $ opam source stdio
>     [...]
>     $ jbuild build @install
>
> This method has been successfully tested to build the ~100 Jane Street
> packages at once.
>
> Changes
> =======
>
> Here is the full set of changes since the first alpha release:
>
> - Added a manual
>
> - Support incremental compilation
>
> - Switched the CLI to cmdliner and added a =build= command
>   (#5, Rudi Grinberg)
>
> - Added a few commands:
>   + =runtest=
>   + =install=
>   + =uninstall=
>   + =installed-libraries=
>   + =exec=: execute a command in an environment similar to what you
>     would get after =jbuilder install=
>
> - Removed the =build-package= command in favor of a =--only-packages=
>   option that is common to all commands
>
> - Automatically generate =.merlin= files
>   (#2, Richard Davison)
>
> - Improve the output of jbuilder, in particular don't mangle the
>   output of commands when using =-j N= with =N > 1=
>
> - Generate a log in =_build/log=
>
> - Versioned the jbuild format and added a first stable version.
>   You should now put =(jbuilder_version 1)= in a =jbuild= file at the
>   root of your project to ensure forward compatibility
>
> - Switch from =ppx_driver= to =ocaml-migrate-parsetree.driver=. In
>   order to use ppx rewriters with Jbuilder, they need to use
>   =ocaml-migrate-parsetree.driver=
>
> - Added support for aliases
>   (#7, Rudi Grinberg)
>
> - Added support for compiling against multiple opam switch
>   simultaneously by writing a =jbuild-worspace= file
>
> - Added support for OCaml 4.02.3
>
> - Added support for architectures that don't have natdynlink
>
> - Search the root according to the rules described in the manual
>   instead of always using the current directory
>
> - extended the action language to support common actions without using
>   a shell:
>   + =(with-stdout-to <file> <DSL>)=
>   + =(copy <src> <dst>)=
>   ...
>
> - Removed all implicit uses of bash or the system shell. Now one has
>   to write explicitely =(bash "...")= or =(system "...")=
>
> - Generate meaningful versions in =META= files
>
> - Strengthen the scope of a package. Jbuilder knows about package
>   =foo= only in the sub-tree starting from where =foo.opam= lives
>
> Notes
> =====
>
> Jbuilder was released in opam today, and since then I got reports that
> it often chooses the wrong "root". The rules for finding the root of
> the current workspace will have to be changed for the 1.0 release. In
> the meantime, you can force the compilation root by writing a
> jbuild-workspace containing "(context default)" where you want the
> root to be.
>
>
> [1] https://github.com/janestreet/jbuilder/blob/master/doc/manual.org
> [2] https://github.com/janestreet/jbuilder/blob/master/doc/quick-start.org
> [3] https://github.com/janestreet/jbuilder
>
> --
> Jeremie Dimino



-- 
Jeremie