doc: add first documentation draft

Fixes #42.

.gitattributes

@@ -1,2 +1,4 @@
+*.bat   -text
+*.png   binary
 .git*   eol=lf export-ignore
 *       eol=lf

doc/.gitignore

@@ -0,0 +1 @@
+/_build/

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/conf.py

@@ -0,0 +1,31 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Basement recipes'
+copyright = '2024, Jan Klötzke'
+author = 'Jan Klötzke'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [ 'sphinx.ext.intersphinx' ]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+highlight_language = "yaml"
+
+intersphinx_mapping = {
+    'bob' : ('https://bob-build-tool.readthedocs.io/en/latest/', None),
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

doc/contribution.rst

@@ -0,0 +1,199 @@
+Contribution guide
+==================
+
+The Bob Build Tool and the Basement project are open-source, community-based
+projects. Contributions are very welcome. The following sections should give
+some guidance how to create new recipes or improve existing ones.
+
+Anatomy of a recipe
+-------------------
+
+The general structure of a recipe looks like the following::
+
+    inherit: [autotools]
+
+    depends:
+        - libs::pcre-lib-1-dev
+        - use: []
+          depends:
+            - libs::pcre-lib-1-tgt
+
+    metaEnvironment:
+        PKG_VERSION: "3.11"
+        PKG_LICENSE: "GPL-3.0-or-later"
+
+    checkoutSCM:
+        scm: url
+        url: ${GNU_MIRROR}/grep/grep-${PKG_VERSION}.tar.xz
+        digestSHA1: "955146a0a4887eca33606e391481bbef37055b86"
+        stripComponents: 1
+
+    buildScript: |
+        autotoolsBuild $1 \
+            --without-included-regex
+
+    packageScript: |
+        autotoolsPackageTgt
+
+    provideDeps: [ "*-tgt" ]
+
+
+1. Any classes that are inherited are named at the top of the recipe. Only
+   include classes that are actually needed.
+2. Usually, recipes depend on other recipes because the package needs other
+   libraries to work. They are named in the
+   :external:ref:`configuration-recipes-depends` section. Notice that each
+   dependency is usually listed twice: the build time library dependency
+   (``-dev``) that has the headers and the static or dynamic libraries. The
+   same dependencies are again listed as runtime dependency. These packages end
+   with the ``-tgt`` suffix by convention.
+3. The :external:ref:`configuration-recipes-metaenv` variables describe the package. So far,
+   two variables should be present:
+
+   ``PKG_VERSION``
+     The version of the package that is built.
+
+   ``PKG_LICENSE``
+     The license of the package as `SPDX License Identifier
+     <https://spdx.org/licenses/>`_. In the best case a single identifier
+     applies. Sometimes, a more complicated license expression (e.g.
+     ``GPL-2.0-only OR BSD-3-Clause``). See the SPDX specification for details
+     how licenses are expressed.
+4. The :external:ref:`configuration-recipes-scm` part fetches the source code.
+   Always make sure that the checkout is determinisitc. This can be a hash sum
+   for tarballs like the example above or a git commit id. If tarballs or other
+   archives are available, they are very much preferred. Only use git clones or
+   other "real" SCMs if release tarballs are not available.
+5. The build script does the actual job of building the package. In case of
+   standard build systems, this should only be a couple of lines, passing
+   necessary configuration options to the standard build system wrappers.
+6. In the ``packageScript`` the desired output is fetched from the build tree
+   of the package.
+7. As a last step, all runtime dependencies are passed downstream by the
+   :external:ref:`configuration-recipes-providedeps` property.
+
+This pattern is the basis for almost all recipes. Some sections might not be
+necessary while others need additional things. See the following sections for
+more information about the various package types.
+
+.. TODO: Multiple packages with different licenses - USe PKG_LICENSE inside of
+   multiPackage
+
+Recipe style guide
+------------------
+
+There are a couple of general coding style rules:
+
+* Indent by 4 spaces
+* Lines should break after 80 characters. The hard line length limit is 120
+  characters.
+* ...
+
+Class style guide
+-----------------
+
+Regarding the functions in classes, the function name should start with the class name.
+The rest of the name is using camel case.
+For example, for class ``foo`` might define functions ``fooBuild`` and ``fooBarBaz``.
+
+Classes should typically have no side effect. They should just declare functions and
+variables in ``checkout/build/packageSetup``.
+
+Recipe naming
+-------------
+
+When creating new recipes, the respective layer must be chosen first. Almost
+always, the ``basement-gnu-linux`` layer is the right one. The only reason to
+put something new into the ``basement`` layer is when it is required to support
+a (new) build system or standard toolchain.
+
+New recipes should be placed next to similar other recipes. Recipes are placed
+into different categories. The following list should provide some guideline to
+choose the right category. It is not uncommon that multiple categories apply.
+In this case, the first matching category of the following list should be used.
+If in doubt, create a discussion on Github or ask on the mailing list.
+
+``libs``
+  C and C++ libraries to make other programs work. Libraries are packages that
+  provide header files and static and/or dynamic libraries that are used by
+  other packages. Even if the package additionally provides some application
+  based on the library, the ``libs`` category should be used.
+
+  Other languages (e.g. Python) have their own category and libraries of these
+  languages should be placed there. On the other hand, there are sometimes
+  large collections of libraries that are related to each other. Such
+  libraries are further put into sub-categories:
+
+  ``gnome``
+    Libraries that are coming from the Gnome project.
+
+  ``xorg``
+    Libraries that are related to the X.Org project.
+
+Some interpreted languages have their own category. This includes the
+interpreter itself, libraries and applications written in this language.
+
+``perl``
+  Everything about Perl.
+
+``python``
+  Everything about Python 3. Support for Python 2 has been removed.
+
+The other categories do not really have a preference between each other.
+
+``bsp``
+  Anything with links to specific hardware or hardware configuration
+  information. These are for example firmware like the Arm Trusted Firmware or
+  boot loaders like Grub.
+
+``core``
+  Basic files and daemons that are essential to boot the system. This includes
+  utilities to administer system resources, manage user accounts, etc.
+
+``db``
+  Database Servers and Clients.
+
+``devel``
+  Development utilities, compilers, development environments, libraries, etc.
+  Basically anything that is required to build other software.
+
+``editors``
+  Software to edit files. Programming environments.
+
+``graphics``
+  Applications, utilities and files that are graphics related.
+
+  ``fonts``
+    Fonts.
+
+  ``gnome``
+    Applications of the GNOME desktop environment.
+
+  ``wayland``
+    Wayland specific applications and utilities.
+
+  ``xorg``
+    X11 specific applications and utilities.
+
+``kernel``
+  Operating System Kernels and related modules.
+
+``multimedia``
+  Codecs and support utilities for audio, images and video.
+
+``net``
+  Daemons and clients to connect the system to the world.
+
+``text``
+  Text processing applications and utilities. This includes dictionaries and
+  converters.
+
+``utils``
+  Shells, utilities for file/disk manipulation, backup and archive tools,
+  system monitoring, input systems, etc. Basically any tool that does not fit
+  in any of the other categories.
+
+``virtual``
+  Virtual packages. Inside the virtual category the sub-categories form the
+  same hierarchy like it would for non-virtual packages. That is, any of the
+  main categories can be present.

doc/index.rst

@@ -0,0 +1,47 @@
+Welcome to the Basement recipes's documentation!
+================================================
+
+.. image:: /BOB_Logo.png
+
+This basement project is a collection of foundational recipes and classes that
+can be included by other projects. Most importantly, it provides ready to use
+classes to handle common build systems and other recurring tasks. Additionally,
+a sandbox and common GCC toolchains are ready-to-use.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   introduction
+   usage
+   contribution
+
+
+Copyright
+---------
+
+This documentation is part of the Basement recipes.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

doc/introduction.rst

@@ -0,0 +1,53 @@
+Introduction
+============
+
+The `Bob Build Tool <https://github.com/BobBuildTool/bob>`_ is a versatile
+build automation tool. While it brings many mechanism, very little policies are
+included. To build actual software, a number of foundational recipes and
+classes are required. The basement layer provides exactly this.
+
+* Classes for standard build systems (e.g. GNU autotools, CMake, ...)
+* Compilers and interpreters for common languages (C/C++, Python, rust)
+* A standard sandbox image
+
+Prerequisites
+-------------
+
+To use the basement layer, the following prerequisites should be fulfilled:
+
+* A Linux or Windows MSYS2 ``x86_64`` system
+* The following basic development tools should be installed
+  * gcc >= 5.x
+  * bash
+  * POSIX awk (GNU awk version >= 3.1.5)
+  * GNU m4
+  * perl >= 5.6.1
+  * GNU tar
+  * gzip
+  * bzip2
+  * rsync
+  * xz-utils
+* The `Bob Build Tool <https://github.com/BobBuildTool/bob>`_
+
+Layer architecture
+------------------
+
+The basement layer is intentionally kept to its bare minimum, providing the
+above mentioned support. Anything that goes beyond that, is supposed to be kept
+in separate layers. Specifically, the following other layers may be of interest:
+
+* `basement-gnu-linux <https://github.com/BobBuildTool/basement-gnu-linux>`_ -
+  Provides many recipes to build a GNU/Linux system. Note that the recipes are
+  not restricted to be used on Linux. It is just that most of the packages are
+  used for that and the name of the layer does not reflect the full breadth any
+  more.
+
+Examples
+--------
+
+There are some examples available that show how the layers are used:
+
+ * `Embedded systems <https://github.com/BobBuildTool/bob-example-embedded>`_
+ * `Linux containers <https://github.com/BobBuildTool/bob-example-containers>`_
+
+

doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd