Update documentation

README.md

@@ -41,11 +41,11 @@ Additional requirements for `build.sh`:
 
 The `packager` (`bap-builder`) has these commands:
  - `build-image` for building Docker images
- - `build-package` for building packages
- - `create-sysroot` for creating sysroot from already built packages
+ - `build-package` for building Packages
+ - `create-sysroot` for creating sysroot from already built Packages
 
 The `build-package` and `create-sysroot` commands are using Git Repository as storage for built
-packages. Given Git Repository must be created before usage.
+Packages. Given Git Repository must be created before usage.
 
 **NOTE:** Detailed use case scenarios is decribed in [UseCaseScenarios](./doc/UseCaseScenarios.md) document.
 
@@ -59,19 +59,19 @@ packages. Given Git Repository must be created before usage.
     cd ../
     ```
 
-2. Build all Docker images needed for the build:
+2. Build Docker image needed for the build:
 
     ```bash
     bap-builder build-image --context ./example --name debian12
     ```
 
-3. Build all packages for the given distro:
+3. Build all Packages for the given distro:
 
     ```bash
     bap-builder build-package --context ./example --image-name debian12 --output-dir ./lfsrepo --all
     ```
 
-4. Create sysroot for built packages:
+4. Create sysroot for built Packages:
 
     ```bash
     bap-builder create-sysroot --context ./example --image-name debian12 --git-lfs ./lfsrepo --sysroot-dir ./new_sysroot

doc/BuildProcess.md

@@ -1,44 +1,75 @@
 
 # Build Process
 
-Each package has a Config file in the JSON format. (Config file details in [Context Directory Structure])
+Each Package has a Config file in the JSON format (Config file details in [Context Structure]).
 
-## Build All packages
+## Build All Packages
 
-### Config phase for all packages
+### Config phase for all Packages
 
-- the default Package config structure is created (with defaults filled in, look for `Config`
-  in the config module).
-- the JSON config for the package is read into Go structure.
-- the default Package config is merged with the confile read from file. The config file
+- the default Package Config structure is created (with defaults filled in, look for `Config`
+  in the bringauto_config module).
+- the JSON Config for the Package is read into Go structure.
+- the default Package Config is merged with the Config read from file. The Config file
   data has a precedence over Default one.
 
-### Build phase for all packages
+### Build phase for all Packages
 
-- the package configs are stored in linear list
-- package config are topological sorted by `Dependencies`,
-- the packages are build from first item of the list (head of the list) to the last package of the list.
+- All Package Configs are stored in linear list
+- All Configs are topological sorted by `Dependencies`,
+- the Packages are build from first item of the list (head of the list) to the last Package of the
+  list.
 
-During the build the package files installed by installation feature of the CMake are copied
-to the `install_sysroot` directory located in the working directory of the builder.
+During the build the Package files installed by installation feature of the CMake are copied
+to the `install_sysroot` directory located in the working directory of the builder. If Package
+build files would overwrite any files already present in sysroot, the build fails (more in
+[Sysroot]).
 
-Each package has a `IsDebug` flag. If the flag is true the package is considered as Debug package.
-If the package is false the package is considered as Release.
+Each Package has a `IsDebug` flag. If the flag is true the Package is considered as Debug Package.
+If the Package is false the Package is considered as Release.
 
-Packages that are marked as Debug has separate sysroot dir in `install_sysroot` directory.  So the Debug and release
-packages are not mixed together.
+Packages that are marked as Debug has separate sysroot dir in `install_sysroot` directory.  So the
+Debug and Release Packages are not mixed together.
 
-## Build single package
+If there is any circular dependency between Packages in build list, the build fails.
 
-### Config phase for single package
+## Build single Package
 
-Same as for All build except that only configs for given `package_group` are read and managed.
+### Config phase for single Package
 
-### Build phase for single package
+Same as for All build except that only Configs for given Package Group are read and managed.
+
+### Build phase for single Package
 
 Same as for All build except that the dependencies are ignored. (so if you have not initialized
-`install_sysroot` then the package build may fail)
+`install_sysroot` then the Package build may fail)
+
+If you want to build Package with all dependencies, you can add `--build-deps` option to script
+call.
+
+## Build single Package with its dependencies
+
+### Config phase for single Package
+
+Same as for All build except that only Configs for given Package Group and all dependencies in
+these Configs recursively are read and managed.
+
+### Build phase for single Package
+
+Same as for All build.
+
+## Build Packages which depends on a Package
+
+### Config phase for single Package
+
+Same as for All build except that only Configs of Packages which depends on given Package and its
+dependencies are read and managed. If the recursive option is triggered, the process is done
+recursively (More in [Use Case Scenarios]).
+
+### Build phase for single Package
 
-If you want to build package with all dependencies, you can add `--build-deps` flag to script call.
+Same as for All build.
 
-[Context Directory Structure]: ./ContextDirectoryStructure.md
+[Context Structure]: ./ContextStructure.md
+[Sysroot]: ./Sysroot.md
+[Use Case Scenarios]: ./UseCaseScenarios.md

doc/CMakeProjectRequirements.md

@@ -7,4 +7,4 @@ Requirements
 
 - Project must be able to be installed by GNU Make - `make install`
 - Project must NOT override `CMAKE_INSTALL_PREFIX` CMake variable - it's used for the project installation to
-  a given directory and package creation. If you override it the build fail!
+  a given directory and Package creation. If you override it the build fail!

doc/PackageJSONStructure.md → doc/ConfigStructure.md

@@ -1,6 +1,8 @@
-# Package JSON Structure
+# Config Structure
 
-This document provides an example of the package configuration file. Note that this example does not follow the JSON format strictly because it contains comments and the values are just sample values. For a better understanding of the JSON format, check the `example/package` directory in this repository.
+This document provides an example of the Config file. Note that this example does not follow the
+JSON format strictly because it contains comments and the values are just sample values. For a
+better understanding of the JSON format, check the `example/package` directory in this repository.
 
 Not all fields are required, and some fields have default values.
 
@@ -28,17 +30,17 @@ Not all fields are required, and some fields have default values.
       }
     }
   },
-  "Package": { // Metadata for the project package
-    "Name": "PackageName", // Package name used to construct the package archive name
+  "Package": { // Metadata for the project Package
+    "Name": "PackageName", // Package name used to construct the Package archive name
     "VersionTag": "v5.98.0", // Detailed in the VersionTag section
     "PlatformString": {
       "Mode": "auto", // Detailed in the Platform_String_Mode section
     },
-    "IsLibrary": true, // If true, adds 'lib' prefix to the package name
-    "IsDevLib": true,  // If true, adds '-dev' suffix to the package name
-    "IsDebug": true    // If true, adds 'd' to the package name (but before the -dev suffix)
+    "IsLibrary": true, // If true, adds 'lib' prefix to the Package name
+    "IsDevLib": true,  // If true, adds '-dev' suffix to the Package name
+    "IsDebug": true    // If true, adds 'd' to the Package name (but before the -dev suffix)
   },
-  "DockerMatrix": { // Specifies the Docker images from the "docker/" directory used to build this package
+  "DockerMatrix": { // Specifies the Docker images from the "docker/" directory used to build this Package
     "ImageNames":  [ "ubuntu1804", "ubuntu2004", "debian11" ]
   }
 }
@@ -70,7 +72,8 @@ Mode = "auto" | "any_machine" | "explicit"
 **auto** - Constructs the PlatformString for a target machine automatically.
 Example for Debian 11 (x86_64): "x86-64-debian-11"
 
-**any_machine** - Constructs the platform string specific only to the Distro name and distro release, with the machine part of the PlatformString set to "any".
+**any_machine** - Constructs the platform string specific only to the Distro name and distro
+release, with the machine part of the PlatformString set to "any".
 Example for Debian 11 (x86_64): "any-debian-11"
 
 **explicit** - User must fill in all three parts manually:

doc/ContextStructure.md

@@ -0,0 +1,43 @@
+
+# Context Structure
+
+Context structure is a directory structure that gathers Configs needed for BAP to
+work.
+
+In the Context the definitions of Packages (Configs) and Docker images are stored.
+
+``` plaintext
+<context_directory>/
+ docker/
+  <docker_name>/
+   Dockerfile
+  ...
+ package/
+  <package_group_name>/
+   <package_config_a>.json
+   <package_config_b>.json
+   ...
+  ...
+```
+
+## Docker Name
+
+The image name is recognized by a name of a directory in the `docker/` directory.
+
+Docker image built by Dockerfile in <docker_name> directory must be tagged by <docker_name>.
+
+You can use `bap-builder build-image` feature to build docker images instead of directly invoke `docker` command.
+
+## Package Group Name
+
+Each Package Group can have multiple Configs.
+
+Each Config represents one Package.
+
+Each Config is a json file.
+
+Each Config must have '.json' extension.
+
+The Config format is described by [ConfigStructure]
+
+[ConfigStructure]: ./ConfigStructure.md

doc/PackageDependencies.md

@@ -1,12 +1,12 @@
 
 # Package Dependencies
 
-Each package can have a one or more dependencies.
+Each Package can have a one or more dependencies.
 
 Basically, we can divide Package dependencies into two sets
 
 - System dependencies - dependencies that must be installed on the host system,
-- Local dependencies - dependencies that are delivered with a package.
+- Local dependencies - dependencies that are delivered with a Package.
 
 The "Dependencies" in our context mean "Local dependencies".
 

doc/PackageRepository.md

@@ -0,0 +1,25 @@
+# Package Repository
+
+The Package Repository is used for storage of built Packages. It is a git repository at the same time.
+The git tool is used for managing consistent storage of Packages.
+
+## Behaviour
+
+At the start of `build-package` and `create-sysroot` commands the Package Repository consistency
+check is performed. If the git status in Package Repository is not empty, the state of Repository
+is considered as non-consistent and the script ends with error. The user should then clean the
+Repository and continue. It is a bug if the non-consistent state is caused by `bap-builder` itself.
+Afterwards the check is comparing Configs currently in Context and built Packages in Package
+Repository. If in Package Repository there is any version of Package which is not in Context, the
+Package Repository is considered as non-consistent and the script ends with error. User needs to
+fix this problem manually and then continue. If some Packages are in Context and are not in Package
+Repository, only warning is printed. All files in `<DISTRO_NAME>/<DISTRO_VERSION/MACHINE_TYPE>` are
+checked, so any other files in this directory (alongside Package directories) will be counted as an
+error. User can't add any files here manually.
+
+During `build-package` command Packages are built in order. Each succesfully built Package is
+copied to Package Repository (specified with cli flag) to specific path -
+`<DISTRO_NAME>/<DISTRO_VERSION/MACHINE_TYPE/PACKAGE_NAME>`. In the end after all Packages are
+succesfully built, all copied files in Package Repository are git committed and remain in
+Repository. If any build fails or the script is interrupted, all copied Packages are removed from
+Repository. This mechanism ensures that the Package Repository is always consistent.

doc/PlatformString.md

@@ -1,6 +1,5 @@
 
 # Platform String
 
-Platform string is a string in form `machine`-`distro`
-
-TODO: detailed description
+Platform string is a string in form `DISTRO_NAME` - `DISTRO_VERSION` - `MACHINE`. It is used for
+Package zip filenames and paths in Package Repository and sysroot directory.