Document `jbuilder subst` in the manual
This commit is contained in:
parent
e3d879dbd8
commit
7dc30d1184
|
@ -351,5 +351,83 @@ However it doesn't provides helpers for distributing it. It is
|
||||||
recommemded to use `Topkg <https://github.com/dbuenzli/topkg>`__ for
|
recommemded to use `Topkg <https://github.com/dbuenzli/topkg>`__ for
|
||||||
this purpose.
|
this purpose.
|
||||||
|
|
||||||
The `topkg-jbuilder <https://github.com/diml/topkg-jbuilder>`__ project
|
The `topkg-jbuilder <https://github.com/diml/topkg-jbuilder>`__
|
||||||
provides helpers for using Topkg in a Jbuilder project.
|
project provides helpers for using Topkg in a Jbuilder project. In
|
||||||
|
particular, as long as your project uses the common defaults, just
|
||||||
|
write this ``pkg/pkg.ml`` file and you are all set:
|
||||||
|
|
||||||
|
.. code:: ocaml
|
||||||
|
|
||||||
|
#use "topfind"
|
||||||
|
#require "topkg-jbuilder.auto"
|
||||||
|
|
||||||
|
It is planned that this file won't be necessary at all soon and topkg
|
||||||
|
will work out of the box on jbuilder projects.
|
||||||
|
|
||||||
|
The common defaults are that your projects include the following
|
||||||
|
files:
|
||||||
|
|
||||||
|
- ``README.md``
|
||||||
|
- ``CHANGES.md``
|
||||||
|
- ``LICENSE.md``
|
||||||
|
|
||||||
|
And that if your project contains several packages, then all the
|
||||||
|
package names must be prefixed by the shortest one.
|
||||||
|
|
||||||
|
Watermarking
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
|
One of the feature topkg provides is watermarking; it replaces various
|
||||||
|
strings of the form ``%%ID%%`` in all files of your project before
|
||||||
|
creating a release tarball or when the package is pinned by the user
|
||||||
|
using opam.
|
||||||
|
|
||||||
|
This is especially interesting for the ``%%VERSION%%`` string, which
|
||||||
|
gets replaced by the version obtained from the vcs. For instance if
|
||||||
|
you are using git, topkg invokes this command to find out the version:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ git describe --always --dirty
|
||||||
|
1.0+beta9-79-g29e9b37
|
||||||
|
|
||||||
|
Projects using jbuilder usually only need topkg for creating and
|
||||||
|
publishing releases. However they might still want to substitute the
|
||||||
|
watermarks when the package is pinned by the user. To help with this,
|
||||||
|
jbuilder provides the ``subst`` sub-command.
|
||||||
|
|
||||||
|
jbuilder subst
|
||||||
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
``jbuilder subst`` performs the same substitution ``topkg`` does with
|
||||||
|
the default configuration. i.e. calling ``jbuilder subst`` at the root
|
||||||
|
of your project will rewrite in place all the files in your project.
|
||||||
|
|
||||||
|
More precisely, it replaces all the following strings in source files:
|
||||||
|
|
||||||
|
- ``%%NAME%%``, the name of the project
|
||||||
|
- ``%%VERSION%%``, output of ``git describe --always --dirty``
|
||||||
|
- ``%%VERSION_NUM%%``, same as ``%%VERSION%%`` but with a potential leading
|
||||||
|
``v`` or ``V`` dropped
|
||||||
|
- ``%%VCS_COMMIT_ID%%``, commit hash from the vcs
|
||||||
|
- ``%%PKG_MAINTAINER%%``, contents of the ``maintainer`` field from the
|
||||||
|
opam file
|
||||||
|
- ``%%PKG_AUTHORS%%``, contents of the ``authors`` field from the opam file
|
||||||
|
- ``%%PKG_HOMEPAGE%%``, contents of the ``homepage`` field from the opam file
|
||||||
|
- ``%%PKG_ISSUES%%``, contents of the ``issues`` field from the opam file
|
||||||
|
- ``%%PKG_DOC%%``, contents of the ``doc`` field from the opam file
|
||||||
|
- ``%%PKG_LICENSE%%``, contents of the ``license`` field from the opam file
|
||||||
|
- ``%%PKG_REPO%%``, contents of the ``repo`` field from the opam file
|
||||||
|
|
||||||
|
Note that if your project contains several packages, ``%%NAME%%`` will
|
||||||
|
be replaced by the shorted package name as long as it is a prefix of
|
||||||
|
all the package names. If your package names don't follow this rule,
|
||||||
|
you need to specify the name explicitly via the ``-n`` flag:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ jbuilder subst -n myproject
|
||||||
|
|
||||||
|
Finally, note that jbuilder doesn't allow you to customize the list of
|
||||||
|
substituted watermarks. If you which to do so, you need to configure
|
||||||
|
topkg and use it instead of ``jbuilder subst``.
|
||||||
|
|
Loading…
Reference in New Issue