rework the documentation of scopes
This commit is contained in:
parent
a392b59fcd
commit
2be5e593d6
|
@ -639,24 +639,6 @@ are part of the installed world, you need to use the public name. For instance:
|
|||
When resolving libraries, libraries that are part of the workspace are always
|
||||
prefered to ones that are part of the installed world.
|
||||
|
||||
Scope of internal library names
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The scope of internal library names is not the whole workspace. It is restricted
|
||||
to the subtree starting from the closest parent containing a ``<package>.opam``
|
||||
file, or the whole workspace if no such directory exist. Moreover, a subtree
|
||||
containing ``<package>.opam`` doesn' t inherit the internal names available in
|
||||
its parent scope.
|
||||
|
||||
The idea behing this rule is that public library names must be universally
|
||||
unique, but internal ones don't need to. In particular you might have private
|
||||
libraries that are only used for tests or building an executable.
|
||||
|
||||
As a result, when you create a workspace including several projects there might
|
||||
be a name clash between internal library names.
|
||||
|
||||
This scoping rule ensure that this won't be a problem.
|
||||
|
||||
.. _alternative-deps:
|
||||
|
||||
Alternative dependencies
|
||||
|
|
|
@ -71,15 +71,33 @@ Declaring a package this way will allow you to add elements such as
|
|||
libraries, executables, documentations, ... to your package by declaring
|
||||
them in ``jbuild`` files.
|
||||
|
||||
Jbuilder will only register the existence of ``<package>`` in the
|
||||
subtree starting where the ``<package>.opam`` file lives, so you can
|
||||
only declare parts of the packages in this subtree. Typically your
|
||||
Such elements can only be declared in the scope defined by the
|
||||
corresponding ``<package>.opam`` file. Typically your
|
||||
``<package>.opam`` files should be at the root of your project, since
|
||||
this is where ``opam pin ...`` will look for them.
|
||||
|
||||
Note that ``<package>`` must be non empty, so in particular ``.opam``
|
||||
files are ignored.
|
||||
|
||||
.. _scopes:
|
||||
|
||||
Scopes
|
||||
------
|
||||
|
||||
Any directory containing at least one ``<package>.opam`` file defines
|
||||
a scope. This scope is the sub-tree starting from this directory,
|
||||
excluding any other scopes rooted in sub-direcotries.
|
||||
|
||||
Typically, any given project will define a single scope. Libraries and
|
||||
executables that are not meant to be installed will be visible inside
|
||||
this scope only.
|
||||
|
||||
Because scopes are exclusive, if you whish to include the dependencies
|
||||
of the project you are currently working on into your workspace, you
|
||||
may copy them in a ``vendor`` directory, or any other name of your
|
||||
choice. Jbuilder will look for them there rather than in the installed
|
||||
world and there will be no overlap between the various scopes.
|
||||
|
||||
Package version
|
||||
---------------
|
||||
|
||||
|
|
|
@ -21,6 +21,17 @@ Terminology
|
|||
- **installed world**: anything outside of the workspace, that Jbuilder
|
||||
takes for granted and doesn't know how to build
|
||||
|
||||
- **installation**: this is the action of copying build artifacts or
|
||||
other files from the ``<root>/_build`` directory to the installed
|
||||
world
|
||||
|
||||
- **scope**: a scope determines where private items are
|
||||
visible. Private items include libraries or binaries that will not
|
||||
be installed. In Jbuilder, scopes are sub-trees rooted where at
|
||||
least one ``<package>.opam`` file is present. Moreover, scopes are
|
||||
exclusive. Typically every project defines a single scope. See
|
||||
:ref:`scopes` for more details
|
||||
|
||||
- **build context**: a build context is a subdirectory of the
|
||||
``<root>/_build`` directory. It contains all the build artifacts of
|
||||
the workspace built against a specific configuration. Without
|
||||
|
|
Loading…
Reference in New Issue