Add an introductory section on how to use site.conf file

It's useful for beginners to appreciate the value of site.conf.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

On Mon, 26 May 2025 at 12:49, Robert P. J. Day via
lists.yoctoproject.org <rpjday=crashcourse.ca@lists.yoctoproject.org>
wrote:
> +Reducing duplication by using a global "site.conf" file
> +=======================================================
> +
> +As you start building multiple images, you will probably notice that you are frequently
> +adding a lot of common content to the new ``local.conf`` in each build directory;
> +this can get tedious and repetitive, but there is a way to centralize all of that
> +common content and pull it into each of your new builds.
> +
> +If your build's ``conf/`` directory contains a file named ``site.conf``, that file
> +will be included in the build's processing before the ``local.conf`` file; this
> +means you can create a single ``site.conf`` file somewhere outside of your build
> +directories and, after creating a new build directory, you can either copy or
> +symlink that file into the ``conf/`` directory, where its contents will be processed
> +before that build's ``local.conf`` (so that you can always set build-specific configuration
> +in ``local.conf`` which will override the more general settings).
> +
> +As a simple example, here's a ``site.conf`` file that will configure, for each
> +build that includes it, settings for a local mirror, that all your builds will
> +be based on ``systemd``, and that you want to build ``.deb`` packages for each build::
> +
> +  SCONF_VERSION = "1"
> +  SOURCE_MIRROR_URL ?= "file:///(where downloaded tarballs are)"
> +  INHERIT += "own-mirrors"
> +  BB_GENERATE_MIRROR_TARBALLS = "1"
> +
> +  INIT_MANAGER = "systemd"
> +
> +  PACKAGE_CLASSES = "package_deb"
> +
> +Again, if a ``site.conf`` file exists, it will be processed before that build's
> +``local.conf`` file, so that any build is free to override ``site.conf`` settings
> +with any build-specific settings in ``local.conf``.

This is too verbose, repeats itself, and is not really correct. I have
to say I'm firmly against this as it's currently written.

site.conf is intended for settings that are specific to the build host
machine (resource constraints, locations for downloads and sstate) or
the network its on (proxies, mirrors).

Anything that is about yocto build itself should go somewhere else,
e.g. openembedded template, or a config fragment, or distro settings.
If you want systemd and deb packaging for all of your builds, then it
definitely a mydistro.conf item.

Alex

On Tue, 27 May 2025, Alexander Kanavin wrote:

> On Mon, 26 May 2025 at 12:49, Robert P. J. Day via
> lists.yoctoproject.org <rpjday=crashcourse.ca@lists.yoctoproject.org>
> wrote:
> > +Reducing duplication by using a global "site.conf" file
> > +=======================================================
> > +
> > +As you start building multiple images, you will probably notice that you are frequently
> > +adding a lot of common content to the new ``local.conf`` in each build directory;
> > +this can get tedious and repetitive, but there is a way to centralize all of that
> > +common content and pull it into each of your new builds.
> > +
> > +If your build's ``conf/`` directory contains a file named ``site.conf``, that file
> > +will be included in the build's processing before the ``local.conf`` file; this
> > +means you can create a single ``site.conf`` file somewhere outside of your build
> > +directories and, after creating a new build directory, you can either copy or
> > +symlink that file into the ``conf/`` directory, where its contents will be processed
> > +before that build's ``local.conf`` (so that you can always set build-specific configuration
> > +in ``local.conf`` which will override the more general settings).
> > +
> > +As a simple example, here's a ``site.conf`` file that will configure, for each
> > +build that includes it, settings for a local mirror, that all your builds will
> > +be based on ``systemd``, and that you want to build ``.deb`` packages for each build::
> > +
> > +  SCONF_VERSION = "1"
> > +  SOURCE_MIRROR_URL ?= "file:///(where downloaded tarballs are)"
> > +  INHERIT += "own-mirrors"
> > +  BB_GENERATE_MIRROR_TARBALLS = "1"
> > +
> > +  INIT_MANAGER = "systemd"
> > +
> > +  PACKAGE_CLASSES = "package_deb"
> > +
> > +Again, if a ``site.conf`` file exists, it will be processed before that build's
> > +``local.conf`` file, so that any build is free to override ``site.conf`` settings
> > +with any build-specific settings in ``local.conf``.
>
> This is too verbose, repeats itself, and is not really correct. I have
> to say I'm firmly against this as it's currently written.
>
> site.conf is intended for settings that are specific to the build host
> machine (resource constraints, locations for downloads and sstate) or
> the network its on (proxies, mirrors).
>
> Anything that is about yocto build itself should go somewhere else,
> e.g. openembedded template, or a config fragment, or distro settings.
> If you want systemd and deb packaging for all of your builds, then it
> definitely a mydistro.conf item.

  OK, fair enough, maybe the quick build doc doesn't need something
this specific. So let's drop it.

rday