Re: [bitbake-devel] [PATCH 4/4] bitbake-setup: implement symlinking local sources into builds

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi,

On Thu Dec 11, 2025 at 3:25 PM CET, Alexander Kanavin via lists.openembedded.org wrote:
[...]
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> index 12b29241f..4d3585f09 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -317,6 +317,17 @@ In addition, the command can take the following arguments:
>  -  ``--skip-selection``: can be used to skip some of the choices
>     (which may result in an incomplete :term:`Setup`!)
>  
> +-  ``-L`` or ``--use-local-source``: instead of getting a source as prescribed in
> +   a configuration, symlink it into a :term:`Setup` from a path on local disk. This
> +   is useful for local development where that particular source directory is managed
> +   separately, and bitbake-setup will include it in a build but will not otherwise
> +   touch or modify it. This option can be specified multiple times to specify multiple
> +   local sources.
> +
> +   The option can be seen as a command line shortcut to providing an override file
> +   with a ``local`` source in it. See the :ref:`ref-bbsetup-source-overrides` section
> +   for more information on source overrides

Missing a period.

> +
>  ``bitbake-setup init`` Examples
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Maybe we could add an example (or extend one) in this section to show how this
new --use-local-source option is used?

>  
> @@ -649,7 +660,8 @@ They contain the following sections:
>            "description": "OpenEmbedded - 'nodistro' basic configuration"
>        }
>  
> --  ``sources`` (*optional*): Git repositories to fetch.
> +-  ``sources`` (*optional*): sources, such as git repositories that should be provided
> +   under ``layers/`` directory of a :term:`Setup`.
>  
>     Example:
>  
> @@ -669,12 +681,31 @@ They contain the following sections:
>                       "rev": "master"
>                   },
>                   "path": "bitbake"
> +             },
> +             "openembedded-core": {
> +                 "local": {
> +                     "path": "~/path/to/local/openembedded-core"
> +                 }
>               }
>           }
>        }
>  
>     Sources can be specified with the following options:
>  
> +   -  ``path`` (*optional*): where the source is extracted, relative to the
> +      ``layers/`` directory of a :term:`Setup`. If unspecified, the name of the
> +      source is used.
> +
> +   -  ``git-remote`` (*optional*): specifies URI, branch and revision of a git
> +      repository to fetch from.

I'd maybe move git-remote below local and just make one bullet point for the
git-remote description. Because at the moment it appears to be under "local".

So like that:

"""
-  ``git-remote`` (*optional*): specifies URI, branch and revision of a git
   repository to fetch from.

   ``git-remote`` entries are specified with the following options:

   -  ``uri`` (**required**): a URI that follows the git URI syntax.
      See https://git-scm.com/docs/git-clone#_git_urls for more information.

   ...
"""

> +
> +   -  ``local`` (*optional*): specifies a path on local disk that should be symlinked
> +      to under ``layers\``. This is useful for local development, where some layer

Should be "/" instead of "\"

> +      or other component used in a build is managed separately, but should still be
> +      available for bitbake-setup driven builds.
> +
> +   ``git-remote`` entries are specified with the following options:
> +
>     -  ``uri`` (**required**): a URI that follows the git URI syntax.
>        See https://git-scm.com/docs/git-clone#_git_urls for more information.
>  
> @@ -688,9 +719,13 @@ They contain the following sections:
>     -  ``branch`` (**required**): the Git branch, used to check that the
>        specified ``rev`` is indeed on that branch.
>  
> -   -  ``path`` (*optional*): where the source is extracted, relative to the
> -      ``layers/`` directory of a :term:`Setup`. If unspecified, the name of the
> -      source is used.
> +   ``local`` entries are specified with the following options:
> +
> +   -  ``path`` (**required**): the path on local disk where the externally
> +      managed source tree is. ``~`` and ``~user`` are expanded to that user's home
> +      directory. Paths in configuration files must be absolute (after possible
> +      ~ expansion), paths in override files can be relative to the directory where
> +      the override file is.

Likewise, I would put this under the description of "local", like git-remote. In
the end it will group and makes things a bit easier to follow IMO.

Otherwise LGTM, thanks for the docs update. :)

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com