diff --git a/doc/jbuild.rst b/doc/jbuild.rst index f28957fe..6be9c16f 100644 --- a/doc/jbuild.rst +++ b/doc/jbuild.rst @@ -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 ``.opam`` -file, or the whole workspace if no such directory exist. Moreover, a subtree -containing ``.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 diff --git a/doc/project-layout-specification.rst b/doc/project-layout-specification.rst index d35bc2d7..2a68a0b9 100644 --- a/doc/project-layout-specification.rst +++ b/doc/project-layout-specification.rst @@ -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 ```` in the -subtree starting where the ``.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 ``.opam`` file. Typically your ``.opam`` files should be at the root of your project, since this is where ``opam pin ...`` will look for them. Note that ```` must be non empty, so in particular ``.opam`` files are ignored. +.. _scopes: + +Scopes +------ + +Any directory containing at least one ``.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 --------------- diff --git a/doc/terminology.rst b/doc/terminology.rst index 3fa9191b..6216ffc8 100644 --- a/doc/terminology.rst +++ b/doc/terminology.rst @@ -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 ``/_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 ``.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 ``/_build`` directory. It contains all the build artifacts of the workspace built against a specific configuration. Without