Fix up manual/roadmap (#11)
* fix a bunch of typos * s/rule/alias/ in the alias section * clarify that multiple exe's in the same dir with a different build conf. are possible
This commit is contained in:
parent
fea880f31f
commit
78a2b27bc1
|
@ -99,7 +99,7 @@ Currently in =(action ...)= fields, when not using =bash= the language
|
||||||
is very limited. It would be nice to add more commands that would
|
is very limited. It would be nice to add more commands that would
|
||||||
guarantee portability and avoid the quoting nightmare of =bash=.
|
guarantee portability and avoid the quoting nightmare of =bash=.
|
||||||
|
|
||||||
FS commands should be straightfoward to implement:
|
FS commands should be straight foward to implement:
|
||||||
- =(copy <src> <dst>)=
|
- =(copy <src> <dst>)=
|
||||||
- =(mkdir <path>)=
|
- =(mkdir <path>)=
|
||||||
- ...
|
- ...
|
||||||
|
|
|
@ -14,14 +14,14 @@ order to encourage a consistent development style.
|
||||||
|
|
||||||
This scheme is inspired from the one used inside Jane Street and
|
This scheme is inspired from the one used inside Jane Street and
|
||||||
adapted to the opam world. It has matured over a long time and is used
|
adapted to the opam world. It has matured over a long time and is used
|
||||||
daily by hundred of developpers, which means that it is highly tested
|
daily by hundred of developers, which means that it is highly tested
|
||||||
and productive.
|
and productive.
|
||||||
|
|
||||||
When using Jbuilder, you give very little and high-level information
|
When using Jbuilder, you give very little and high-level information
|
||||||
to the build system, which in turns takes care of all the low-level
|
to the build system, which in turns takes care of all the low-level
|
||||||
details, from the compilation of your libraries, executables and
|
details, from the compilation of your libraries, executables and
|
||||||
documentation to the installation, setting up of tests, setting up of
|
documentation to the installation, setting up of tests, setting up of
|
||||||
the devepment tools such as merlin, etc...
|
the development tools such as merlin, etc...
|
||||||
|
|
||||||
In addition to the normal features one would expect from a build
|
In addition to the normal features one would expect from a build
|
||||||
system for OCaml, Jbuilder provides a few additional ones that detach
|
system for OCaml, Jbuilder provides a few additional ones that detach
|
||||||
|
@ -75,7 +75,7 @@ format and the third one describes how to use the =jbuilder= command.
|
||||||
=<root>/_build= directory. It contains all the build artifacts of
|
=<root>/_build= directory. It contains all the build artifacts of
|
||||||
the workspace built against a specific configuration. Without
|
the workspace built against a specific configuration. Without
|
||||||
specific configuration from the user, there is always a =default=
|
specific configuration from the user, there is always a =default=
|
||||||
build context, which correspond to the environemnt in which Jbuilder
|
build context, which correspond to the environment in which Jbuilder
|
||||||
is executed. Build contexts can be specified by writing a
|
is executed. Build contexts can be specified by writing a
|
||||||
[[jbuild-workspace]] file
|
[[jbuild-workspace]] file
|
||||||
|
|
||||||
|
@ -84,7 +84,7 @@ format and the third one describes how to use the =jbuilder= command.
|
||||||
|
|
||||||
- *alias*: an alias is a build target that doesn't produce any file
|
- *alias*: an alias is a build target that doesn't produce any file
|
||||||
and has configurable dependencies. Alias are per-directory and some
|
and has configurable dependencies. Alias are per-directory and some
|
||||||
are recursive; asking an alias to be built in a given directrory
|
are recursive; asking an alias to be built in a given directory
|
||||||
will trigger the construction of the alias in all children
|
will trigger the construction of the alias in all children
|
||||||
directories recursively. The most interesting ones are:
|
directories recursively. The most interesting ones are:
|
||||||
+ =runtest= which runs user defined tests
|
+ =runtest= which runs user defined tests
|
||||||
|
@ -96,15 +96,17 @@ A typical jbuilder project will have one or more =<package>.opam= file
|
||||||
at toplevel as well as =jbuild= files wherever interesting things are:
|
at toplevel as well as =jbuild= files wherever interesting things are:
|
||||||
libraries, executables, tests, documents to install, etc...
|
libraries, executables, tests, documents to install, etc...
|
||||||
|
|
||||||
It is recommemded to organize your project so that you have exactly
|
It is recommended to organize your project so that you have exactly one library
|
||||||
one library per directory. You can have several executables in the
|
per directory. You can have several executables in the same directory, as long
|
||||||
same directory, as long as they share the same build configuration.
|
as they share the same build configuration. If you'd like to have multiple
|
||||||
|
executables with different configurations in the same directory, you will have
|
||||||
|
to make an explicit module list for every executable using =modules=.
|
||||||
|
|
||||||
The rest of these sections describe the format of Jbuilder metadata
|
The rest of these sections describe the format of Jbuilder metadata
|
||||||
files.
|
files.
|
||||||
|
|
||||||
Note that the Jbuilder metadata format is versionned in order to
|
Note that the Jbuilder metadata format is versioned in order to
|
||||||
ensure forward compatibilty. Jane Street packages use a special
|
ensure forward compatibility. Jane Street packages use a special
|
||||||
=jane_street= version which correspond to a rolling and unstable
|
=jane_street= version which correspond to a rolling and unstable
|
||||||
version that follows the internal Jane Street development. You
|
version that follows the internal Jane Street development. You
|
||||||
shouldn't use this in your project, it is only intended to make the
|
shouldn't use this in your project, it is only intended to make the
|
||||||
|
@ -238,7 +240,7 @@ roadmap]] for details.
|
||||||
The following sections describe the available stanzas and their
|
The following sections describe the available stanzas and their
|
||||||
meaning.
|
meaning.
|
||||||
|
|
||||||
**** jbuid_verrsion
|
**** jbuid_version
|
||||||
|
|
||||||
=(jbuild_version 1)= specifies that we are using the version 1 of the
|
=(jbuild_version 1)= specifies that we are using the version 1 of the
|
||||||
Jbuilder metadata format in this =jbuild= file.
|
Jbuilder metadata format in this =jbuild= file.
|
||||||
|
@ -269,7 +271,7 @@ the library and you are free to expose only the modules you want.
|
||||||
=<optional-fields>= are:
|
=<optional-fields>= are:
|
||||||
|
|
||||||
- =(public_name <name>)= this is the name under which the library can
|
- =(public_name <name>)= this is the name under which the library can
|
||||||
be refered as a dependency when it is not part of the current
|
be referred as a dependency when it is not part of the current
|
||||||
workspace, i.e. when it is installed. Without a =(public_name ...)=
|
workspace, i.e. when it is installed. Without a =(public_name ...)=
|
||||||
field, the library will not be installed by Jbuilder. The public
|
field, the library will not be installed by Jbuilder. The public
|
||||||
name must start by the package name it is part of and optionally
|
name must start by the package name it is part of and optionally
|
||||||
|
@ -289,7 +291,7 @@ the library and you are free to expose only the modules you want.
|
||||||
need to start with a uppercase letter. For instance to exclude module
|
need to start with a uppercase letter. For instance to exclude module
|
||||||
=Foo=: =(modules (:standard \ foo))=
|
=Foo=: =(modules (:standard \ foo))=
|
||||||
|
|
||||||
- =(libraries (<library-dependencies>))= is used to specifiy the
|
- =(libraries (<library-dependencies>))= is used to specify the
|
||||||
dependencies of the library. In here you should put library
|
dependencies of the library. In here you should put library
|
||||||
names. For library that are present in the workspace, you can use
|
names. For library that are present in the workspace, you can use
|
||||||
either the real name or the public name. For libraries that are part
|
either the real name or the public name. For libraries that are part
|
||||||
|
@ -301,7 +303,7 @@ the library and you are free to expose only the modules you want.
|
||||||
- =(wrapped <boolean>)= specifies whether the modules of the library
|
- =(wrapped <boolean>)= specifies whether the modules of the library
|
||||||
should be available only through of the toplevel library module, or
|
should be available only through of the toplevel library module, or
|
||||||
should all be exposed at toplevel. The default is =true= and it is
|
should all be exposed at toplevel. The default is =true= and it is
|
||||||
highly recommed to keep it this way. Because OCaml toplevel modules
|
highly recommended to keep it this way. Because OCaml toplevel modules
|
||||||
must all be unique when linking an executables, polluting the
|
must all be unique when linking an executables, polluting the
|
||||||
toplevel namespace will make your library unusable with other
|
toplevel namespace will make your library unusable with other
|
||||||
libraries if there is a module name clash. This option is only
|
libraries if there is a module name clash. This option is only
|
||||||
|
@ -383,7 +385,7 @@ with [[https://github.com/janestreet/configurator][configurator]] by using =(c_f
|
||||||
**** executables
|
**** executables
|
||||||
|
|
||||||
The =executables= stanza must be used to describe sets of
|
The =executables= stanza must be used to describe sets of
|
||||||
executables. The format of executables stanzas is as follow:
|
executables. The format of executables stanzas is as follows:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(executables
|
(executables
|
||||||
|
@ -482,7 +484,7 @@ an action to run to construct the alias.
|
||||||
The syntax is as follow:
|
The syntax is as follow:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(rule
|
(alias
|
||||||
((name <alias-name>)
|
((name <alias-name>)
|
||||||
(deps (<deps-conf list>))
|
(deps (<deps-conf list>))
|
||||||
<optional-fields>
|
<optional-fields>
|
||||||
|
@ -503,7 +505,7 @@ The syntax is as follow:
|
||||||
The typical use of the =alias= stanza is to define tests:
|
The typical use of the =alias= stanza is to define tests:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(rule
|
(alias
|
||||||
((name runtest)
|
((name runtest)
|
||||||
(deps (my-test-program.exe))
|
(deps (my-test-program.exe))
|
||||||
(action "./${<} blah")))
|
(action "./${<} blah")))
|
||||||
|
@ -524,7 +526,7 @@ The syntax is as follow:
|
||||||
(provides (<name> (file <filename>)))
|
(provides (<name> (file <filename>)))
|
||||||
#+end_src
|
#+end_src
|
||||||
|
|
||||||
=<name>= is the name under which the artefact can be refered and
|
=<name>= is the name under which the artifact can be referred and
|
||||||
=<filename>= is the file it resolves to. When =<filename>= can be
|
=<filename>= is the file it resolves to. When =<filename>= can be
|
||||||
guessed from the =<name>=, you can use the following shorter syntax:
|
guessed from the =<name>=, you can use the following shorter syntax:
|
||||||
|
|
||||||
|
@ -640,7 +642,7 @@ Jbuilder supports the following variables:
|
||||||
- =ocaml_version= is the version of the compiler used in the current
|
- =ocaml_version= is the version of the compiler used in the current
|
||||||
build context
|
build context
|
||||||
- =ocaml_where= is the output of =ocamlc -where=
|
- =ocaml_where= is the output of =ocamlc -where=
|
||||||
- =ARCH_SIXTYFOUR= is =true= if using a compiler targetting a 64 bit
|
- =ARCH_SIXTYFOUR= is =true= if using a compiler targeting a 64 bit
|
||||||
architecture and =false= otherwise
|
architecture and =false= otherwise
|
||||||
|
|
||||||
In addition, =(action ...)= fields support the following special variables:
|
In addition, =(action ...)= fields support the following special variables:
|
||||||
|
@ -652,7 +654,7 @@ In addition, =(action ...)= fields support the following special variables:
|
||||||
which case it will expand to =<path>= from the host build context
|
which case it will expand to =<path>= from the host build context
|
||||||
- =bin:<program>= expands to a path to =program=. If =program= is
|
- =bin:<program>= expands to a path to =program=. If =program= is
|
||||||
provided by a jbuild in the workspace (see [[provides][provides stanzas]]), the
|
provided by a jbuild in the workspace (see [[provides][provides stanzas]]), the
|
||||||
locally built binarry will be used, otherwise it will be searched in
|
locally built binary will be used, otherwise it will be searched in
|
||||||
the =PATH= of the current build context
|
the =PATH= of the current build context
|
||||||
- =findlib:<public-library-name>:<file>= expands to a path to file
|
- =findlib:<public-library-name>:<file>= expands to a path to file
|
||||||
=<file>= of library =<public-library-name>=. If
|
=<file>= of library =<public-library-name>=. If
|
||||||
|
@ -685,7 +687,7 @@ Select forms are specified as follow:
|
||||||
- =<library-name>=, which will evaluate to true if =<library-name>= is
|
- =<library-name>=, which will evaluate to true if =<library-name>= is
|
||||||
available, either in the worksapce either in the installed world
|
available, either in the worksapce either in the installed world
|
||||||
- =!<library-name>=, which will evaluate to true if =<library-name>=
|
- =!<library-name>=, which will evaluate to true if =<library-name>=
|
||||||
is not availale in the workspace or in the installed world
|
is not available in the workspace or in the installed world
|
||||||
|
|
||||||
When evaluating a select form, Jbuilder will create
|
When evaluating a select form, Jbuilder will create
|
||||||
=<target-filename>= by copying the file given by the first
|
=<target-filename>= by copying the file given by the first
|
||||||
|
@ -757,7 +759,7 @@ For instance:
|
||||||
|
|
||||||
***** Dependency specification
|
***** Dependency specification
|
||||||
|
|
||||||
Dependecies in =jbuild= files can be specified using one of the
|
Dependencies in =jbuild= files can be specified using one of the
|
||||||
following syntax:
|
following syntax:
|
||||||
|
|
||||||
- =(file <filename>)= or simply =<filename>=: depend on this file
|
- =(file <filename>)= or simply =<filename>=: depend on this file
|
||||||
|
@ -830,7 +832,7 @@ of these two forms:
|
||||||
In both case, all atoms in the argument of this field supports
|
In both case, all atoms in the argument of this field supports
|
||||||
[[Variables
|
[[Variables
|
||||||
expansion][variables expansion]]. Moreover, you don't need to specify dependencies
|
expansion][variables expansion]]. Moreover, you don't need to specify dependencies
|
||||||
explicitely for the special =${exe:...}=, =${bin:...}= or
|
explicitly for the special =${exe:...}=, =${bin:...}= or
|
||||||
=${findlib:...}= forms, these are recognized automatically by
|
=${findlib:...}= forms, these are recognized automatically by
|
||||||
Jbuilder.
|
Jbuilder.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue