@@ -70,7 +70,7 @@ Repeat for `/etc/apache2/sites-available/default-ssl.conf`.
== Set Up BIND
-A DNS server is necessary to resolve `localhost` from `buildchroot-target`.
+A DNS server is necessary to resolve `localhost` from `sbuild-chroot-target`.
```
sudo apt-get install bind9
@@ -62,41 +62,39 @@ hello-isar demo application will be processed 3 times for each
environment. Three different sets of stamps will be used to distinguish
build progress between different bitbake configurations.
-## 2.3 Buildchroot
+## 2.3 Schroot rootfs
+Also called sbuild chroot rootfs, because of the usage by sbuild tool.
One of the key aspect of Debian philosophy claims the fact, that everything in
Debian should be built within Debian environment. To follow this rule, Isar
-introduces the new component - buildchroot. Bulidchroot is typical Debian
-filesystem that is created using standard Debian tools: debootstrap, apt. The
-source of packages can be either official Debian repositories or custom
-repositories created by user. Buildchroot could be one of the following type:
+introduces the new component - schroot rootfs. Schroot rootfs is typical Debian
+filesystem that is created using standard Debian tools: debootstrap, apt-get.
+The source of packages can be either official Debian repositories or custom
+repositories created by user. It could be one of the following type:
- - `buildchroot-host` with the host architecture for cross-compilation.
+ - `sbuild-chroot-host` with the host architecture for cross-compilation.
- - `buildchroot-target` with the target architecture for target native
+ - `sbuild-chroot-target` with the target architecture for target native
compilation.
-Buildchroot lifecycle can be described as following:
+Schroot rootfs lifecycle can be described as following:
- - Buildchroot starts out with a minimal base system that was generated by the
- isar-bootstrap-[host,target] recipe that uses debootstrap and apt.
+ - Schroot rootfs starts out with a minimal base system that was generated by
+ the isar-bootstrap-{host,target} recipe that uses debootstrap and apt-get.
- - During building custom Debian package, list of its build dependencies is
- installed to buildchroot.
-
- - When package has been built, it's installed to current buildchroot to
- satisfy further packages build dependencies.
+ - Common development packages needed for packages building are installed on
+ top of this rootfs.
## 2.4 Target Root Filesystem
-Target filesystem is quite similar to buildchroot. The only difference is that
-it doesn't have development packages installed and always has target
+Target filesystem is quite similar to schroot rootfs. The only difference is
+that it doesn't have development packages installed and always has target
architecture.
Target filesystem lifecycle can be described as following:
- - Target filesystem starts, like the buildchroot, with the same minimal base
- system generated by the isar-bootstrap recipe.
+ - Target filesystem starts, like the schroot rootfs, with the same minimal
+ base system generated by the isar-bootstrap recipe.
- According to the list of custom packages in bitbake recipes, the initial
filesystem will be populated by successfully built packages from locally
@@ -112,7 +110,7 @@ Whole Isar build process can be split into the following steps:
apt for each configuration requested by the user (Debian distro, machine and
architecture).
- - Generation of initial buildchroots for each configuration.
+ - Generation of initial schroot rootfs for each configuration.
- Generation of initial target filesystems for each configuration.
@@ -157,45 +155,42 @@ This recipe implements several tasks which are executed in this order:
minimal base system, that can be used by the other recipes, that depend on
isar-bootstrap.
-## 3.3 Initial Buildchroot Generation
+## 3.3 Initial Schroot Rootfs Generation
-As mentioned above, initial buildchroot is generated using the minimal base
+As mentioned above, initial schroot rootfs is generated using the minimal base
system generated by isar-bootstrap. The bitbake recipe which is responsible for
-buildchroot can be found here:
-`meta/recipes-devtools/buildchroot/buildchroot-[host,target].bb`
+schroot rootfs can be found here:
+`meta/recipes-devtools/sbuild-chroot/sbuild-chroot-{host,target}.bb`
Section 3.8 describes when host or target architecture is used, please refer
to it for more details.
-This recipe implements `do_build` task which performs the following:
+This recipe implements rootfs preparation for the next schroot usage and
+performs the following:
+
+1. Calls `rootfs_prepare` helper function that copies the minimal base system
+ to the schroot rootfs working directory.
-1. Calls the `setup_root_file_system` helper function defined in
- `meta/classes/isar-bootstrap-helper.bbclass` that copies the minimal base
- system to the buildchroot working directory, sets up the isar-apt repository
- which will later contain all isar-build packages, calls update on just this
- repository and installs all packages given via a parameter to this system.
- Those are, in buildchroots case, the basic package building toolchain.
+2. Sets up the isar-apt repository which will later contain all isar-build
+ packages. Also configure apt to retry and not install recommended packages.
-2. Install script for building custom Debian packages:
- `meta/recipes-devtools/buildchroot/files/build.sh`.
+3. Mounts dev, proc, sys and also isar-apt, base-apt into schroot rootfs.
-3. Installs and executes a configuration script, that further customizes the
- buildchroot. For instance it sets the locale settings.
+4. Calls apt-get update, imports package download cache and installs the
+ packages specified as an argument to this rootfs. Those are, in schroot
+ rootfs case, the basic package building toolchain.
-The single stamp is created for each user buildchroot configuration.
+The single stamp is created for each user schroot rootfs configuration.
## 3.4 Initial Target Filesystem Generation
-Initial target filesystem generation process is very similar to buildchroot
+Initial target filesystem generation process is very similar to schroot rootfs
creating, the difference is only in initial packages list.
Target image recipes are the part of Isar core. There is a sample of typical
Isar image that can be customized according to the user requirements:
`meta-isar/recipes-core/images/isar-image-base.bb`.
-Like for buildchroot, the configuration files for image can be found
-here: `meta-isar/recipes-core/images/files`, and it implements `do_build` task.
-
## 3.5 Building Custom Packages
Isar provides the possibility to build Debian packages from sources. This
@@ -217,12 +212,12 @@ Both consist of the following steps:
3. Task `do_install` _only_ for `dpkg-raw`: copy all you want in your
debian package to `${D}`, install hooks in `${D}/DEBIAN`
-4. Task `do_prepare': perform any preparation steps to the unpacked/patched
+4. Task `do_prepare`: Perform any preparation steps to the unpacked/patched
sources before the build. This task calls the dpkg_prepare shell function
- with the buildchroot mounts in place (`dpkg_do_mounts')
+ with the schroot rootfs mounts in place (`dpkg_do_mounts`).
4.1. the `dpkg_prepare` function of `dpkg.bbclass` runs `/isar/deps.sh` in
- the buildchroot. That performs the following:
+ the chroot rootfs. That performs the following:
1. Go to `/home/build/${PN}`
@@ -232,12 +227,12 @@ Both consist of the following steps:
recipe meta-data into a debian/control file suitable for packaging
with dpkg-deb
-5. Task `do_build`: mount folder (`dpkg_do_mounts') with unpacked files to buildchroot,
- execute the actual build function `dpkg_runbuild`, and finally umount again
- (`dpkg_undo_mounts')
+5. Task `do_build`: Mount folder (`dpkg_do_mounts`) with unpacked files to
+ schroot rootfs, execute the actual build function `dpkg_runbuild`, and
+ finally unmount again (`dpkg_undo_mounts`).
5.1. the `dpkg_runbuild` function of `dpkg.bbclass` runs `build.sh` in the
- buildchroot. That performs the following:
+ schroot rootfs. That performs the following:
1. Go to `/home/build/${PN}`
@@ -274,15 +269,15 @@ This process contains the following steps:
## 3.8 Cross-compilation
-Isar provides possibility to cross-compile all or individual packages. There is
-variable ISAR_CROSS_COMPILE that could be set globaly for whole Isar build,
-but also it could be overwritten from the individual recipe to force specific
-compilation mode for it. This variable influences on which buildchroot will be
-used for recipe compilation. Isar is free from packages modification to perform
-cross-compilation, this is done by the same tools as for native compilation.
-Depending on ISAR_CROSS_COMPILE value, additional architecture specifiers are
-passed to build tools automatically, so this is absolutely transparent from
-the user point of view.
+Isar provides the possibility to cross-compile all or individual packages. If
+`ISAR_CROSS_COMPILE` variable is set to 0, the native toolchain will be used
+(e.g., when building for arm64 on amd64, the arm64 gcc binaries will be
+executed in an emulated environment). If set to 1, the cross-toolchain will be
+used (the amd64 cross-gcc binaries will be executed). The default is 0. The
+variable can be set globally for the whole build (e.g., in `local.conf` or
+multiconfig files) or overridden in individual recipes. Cross-compilation
+support must be implemented in source packages. Debian's standard
+cross-toolchains are used for cross-building.
## 3.9 Additional features
@@ -34,7 +34,9 @@ Isar provides:
- Fast target image generation: About 10 minutes to get base system image for one machine.
- Use any apt package provider, including open-source communities like `Debian`, `Raspbian`, etc. and proprietary ones created manually.
- - Native compilation: Packages are compiled in a `chroot` environment using the same toolchain and libraries that will be installed to the target filesystem.
+ - Native compilation: Packages are compiled in a `schroot` environment using
+ the same toolchain and libraries that will be installed to the target
+ filesystem.
- Cross compilation: Could be enabled, when native compilation from the sources takes a lot of time f.e. for Linux kernel.
- Product templates that can be quickly re-used for real projects.
@@ -111,7 +113,7 @@ unstable/bullseye included in `/etc/apt/sources.list[.d]`).
Notes:
-* BitBake requires Python 3.4+.
+* BitBake requires Python 3.6+.
* The python3 package is required for the correct `alternatives` setting.
* If you'd like to run bitbake in a container (chroot, docker, etc.), install
the above in the container, and also perform `sudo apt-get install
@@ -322,6 +324,11 @@ docker run --rm -ti --volume "$(pwd):/build" isar-image-base-debian-buster-armhf
`chroot`(8) runs a command within a specified root directory. Please refer to GNU coreutils online help: <http://www.gnu.org/software/coreutils/> for more information.
+### Schroot
+
+Schroot allows the user to run a command in a chroot environment specified by
+root directory or previously opened session.
+
### QEMU
QEMU is a generic and open source machine emulator and virtualizer. Please refer to <http://wiki.qemu.org/Main_Page> for more information.
@@ -344,7 +351,7 @@ BitBake is a generic task execution engine for efficient execution of shell and
Isar workflow consists of stages described below.
-### Generation of Buildchroot Filesystem
+### Generation of Schroot Filesystem
This filesystem is used as a build environment to compile custom packages. It is generated using `apt` binaries repository, selected by the user in configuration file. Please refer to distro configuration chapter for more information.
@@ -354,7 +361,9 @@ During this stage Isar processes custom packages selected by the user and genera
### Generation of Basic Target Filesystem
-This filesystem is generated similarly to the `buildchroot` one using the `apt` binaries repository. Please refer to distro configuration chapter for more information.
+This filesystem is generated similarly to the `schroot` one using the `apt`
+binaries repository. Please refer to distro configuration chapter for more
+information.
### Install Custom Packages
@@ -426,7 +435,9 @@ Some other variables include:
## Isar Distro Configuration
-In Isar, each machine can use its specific Linux distro to generate `buildchroot` and target filesystem. By default, Isar provides configuration files for the following distros:
+In Isar, each machine can use its specific Linux distro to generate `schroot`
+and target filesystem. By default, Isar provides configuration files for the
+following distros:
- debian-buster
- debian-bullseye
@@ -603,12 +614,12 @@ The IMAGE_CMD is a shell function, and the environment has some pre-set
variables:
- `IMAGE_FILE_HOST` and `IMAGE_FILE_CHROOT` are the paths of the output image
- (including extension) in the host or buildchroot.
+ (including extension) in the host or schroot rootfs.
- `SUDO_CHROOT` is a prefix you can use to have a command run inside the
- buildchroot.
+ imager schroot rootfs.
If the code you provide in `IMAGE_CMD` requires the building and/or installation
-of additional packages in the buildchroot, you can specify this:
+of additional packages in the imager schroot rootfs, you can specify this:
```
IMAGER_BULID_DEPS:my_image = "my_command"
IMAGER_INSTALL:my_image = "my_command"
@@ -972,7 +983,7 @@ concept.
Isar can build 32-bit packages as part of a 64-bit image build and also enable
the image with the necessary packages. To activate compat support,
set `ISAR_ENABLE_COMPAT_ARCH = "1"` in `local.conf`. This will install necessary
-build dependencies in the buildchroot.
+build dependencies in the schroot rootfs.
For all dpkg package recipes, Isar automatically provides a `<package>-compat`
target that builds the package for the `COMPAT_DISTRO_ARCH`. This can be
@@ -985,7 +996,7 @@ scenarios, or when generating an SDK), Isar automatically provides a
### Cross Support for Imagers
If `ISAR_CROSS_COMPILE = "1"`, the imager and optional compression tasks
-run in the host buildchroot instead of the target buildchroot.
+run in the host schroot rootfs instead of the target one.
This gives a significant speedup when compressing the generated image,
as the compression is not emulated.
@@ -993,10 +1004,10 @@ In case your setup does not support cross-imaging, you can disable this
just for the particular image by adding `ISAR_CROSS_COMPILE = "0"` to your
image recipe.
-## Examining and debugging package generation inside their buildchroot
+## Examining and debugging package generation inside their schroot rootfs
Just like OpenEmbedded, Isar supports a devshell target for all dpkg package
-recipes. This target opens a terminal inside the buildchroot that runs the
+recipes. This target opens a terminal inside the schroot rootfs that runs the
package build. To invoke it, just call
`bitbake mc:${MACHINE}-${DISTRO}:<package_name> -c devshell`.
@@ -1029,12 +1040,12 @@ feature known from OpenEmbedded. Isar caches
* the Debian bootstrap (`isar-bootstrap` recipe)
* Debian packages (built with the `dpkg` or `dpkg-raw` classes)
- * root file systems (buildchroot and image rootfs)
+ * root file systems (schroot and image rootfs)
The location of the sstate-cache is controlled by the variable `SSTATE_DIR`
and defaults to `${TMPDIR}/sstate-cache`.
-Note that cached rootfs artifacts (bootstrap and buildchroot) have a limited
+Note that cached rootfs artifacts (bootstrap and schroot rootfs) have a limited
"lifetime": Isar updates their package lists for the upstream package sources
only once, when they are initially created. So as packages on the upstream
mirrors change, those lists will be out-of-date and the rootfs becomes useless.
@@ -1334,14 +1345,14 @@ to have Debian source packages as well.
- Trigger download of Debian source packages as part of rootfs postprocess.
-With the current base-apt implementation, we already cache all the binary packages that
-we download and install onto the target rootfs and buildchroot. This is then used to
-generate a local-apt for offline build.
+With the current base-apt implementation, we already cache all the binary
+packages that we download and install onto the target rootfs and schroot
+rootfs. This is then used to generate a local-apt for offline build.
-Use rootfs postprocessing to parse through the list of deb files in ${DEBDIR} and
-download the corresponding Debian source file using "apt-get source" command.
-This caches the sources of all the Debian packages that are downloaded and installed onto
-the target rootfs and buildchroots.
+Use rootfs postprocessing to parse through the list of deb files in ${DEBDIR}
+and download the corresponding Debian source file using "apt-get source"
+command. This caches the sources of all the Debian packages that are downloaded
+and installed onto the target rootfs and schroot rootfs.
By default, the Debian source caching is not enabled.
To enable it, add the below line to your local.conf file.
Describe schroot rootfs instead of buildchroot. Signed-off-by: Anton Mikanovich <amikan@ilbers.de> --- doc/offline.md | 2 +- doc/technical_overview.md | 107 ++++++++++++++++++-------------------- doc/user_manual.md | 53 +++++++++++-------- 3 files changed, 84 insertions(+), 78 deletions(-)