From 3096c2d77c12757aaa6c259536d54a6b82b9d695 Mon Sep 17 00:00:00 2001 From: Carles Fernandez Date: Thu, 9 May 2024 21:20:46 +0200 Subject: [PATCH] Improve instructions following Xavier Guerrero's suggestions --- README.md | 105 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 64 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index eae954a..155bd3d 100644 --- a/README.md +++ b/README.md @@ -15,16 +15,13 @@ SPDX-FileCopyrightText: 2020-2024 Carles Fernandez-Prades **G**NSS-SDR for **E**mbedded G**N**U/L**i**n**ux**. @@ -36,7 +33,13 @@ G**N**U/L**i**n**ux**. Get a powerful machine (as much RAM, storage capacity, and CPU cores as you can) and [install the Docker engine](https://docs.docker.com/engine/install/) on it. -Make sure that it is up and running. +Make sure that it is up and running. After the installation method of your +preference, you may find useful to add your user to the `docker` group, so you +will not need `sudo` to execute Docker commands: + +``` +$ sudo usermod -aG docker +``` > Note: the `geniux-builder.sh` script makes use of the `zip` and `unzip` tools. > On Debian/Ubuntu machines, you can install them by doing: @@ -77,10 +80,10 @@ Options: Environment variables that affect behavior: GENIUX_MIRROR_PATH Base path to local mirror. Only used if set. - e.g.: 'export GENIUX_MIRROR_PATH=/home/carlesfernandez/mirror' + e.g.: 'export GENIUX_MIRROR_PATH=/home/${USER}/mirror' The mirror is expected to be at '$GENIUX_MIRROR_PATH/sources/$version' GENIUX_STORE_PATH Path in which products will be stored. Only used if set. - e.g.: 'export GENIUX_STORE_PATH=/home/carlesfernandez/geniux-releases' + e.g.: 'export GENIUX_STORE_PATH=/home/${USER}/geniux-releases' GENIUX_STORE_REQUIRES_SUDO If set, the script will ask for super-user privileges to write in the store. You will be asked only once at the beginning. The password will not be revealed. e.g.: 'export GENIUX_STORE_REQUIRES_SUDO=1' @@ -90,16 +93,16 @@ Before calling the script, you might want to set some (optional) environment variables on your host machine: ``` -$ export GENIUX_MIRROR_PATH=/home/user/mirror -$ export GENIUX_STORE_PATH=/home/user/geniux-releases +$ export GENIUX_MIRROR_PATH=/home/${USER}/mirror +$ export GENIUX_STORE_PATH=/home/${USER}/geniux-releases $ export GENIUX_STORE_REQUIRES_SUDO=1 ``` Examples of usage: > NOTE: if you are operating on a remote host through `ssh`, you might want to -> run `screen` at this point, so the work won't be lost in case of a session -> drop. +> run `screen` ot `tmux` at this point, so the work won't be lost in case of a +> session drop. - Build Geniux release `dunfell`, with manifest date `latest`, for machines `zedboard-zynq7` and `raspberrypi3`: @@ -157,8 +160,8 @@ Examples of usage: $ ./geniux-builder.sh honister latest zcu208-zynqmp ``` -- Build Geniux release `kirkstone`, with manifest date `latest`, only for machine - `raspberrypi4-64`: +- Build Geniux release `kirkstone`, with manifest date `latest`, only for + machine `raspberrypi4-64`: ``` $ ./geniux-builder.sh kirkstone latest raspberrypi4-64 @@ -171,8 +174,8 @@ Examples of usage: $ ./geniux-builder.sh langdale latest raspberrypi4-64 ``` -- Build Geniux release `scarthgap`, with manifest date `latest`, only for machine - `raspberrypi5`: +- Build Geniux release `scarthgap`, with manifest date `latest`, only for + machine `raspberrypi5`: ``` $ ./geniux-builder.sh scarthgap latest raspberrypi5 @@ -188,14 +191,18 @@ new features or recipes, fixing bugs, etc.), then you can skip running the container generated by the `geniux-builder.sh` script and follow the instructions below. - ## Generating Geniux images and the SDK installer step-by-step ### Non-interactive method +Overall, the whole build process will take several hours. At its ending, the +image files will be under your `./output` folder, so _outside_ the container. +The `./output` folder must be empty before starting the run. The container +itself will be erased after completion or failure. + > NOTE: if you are operating on a remote host through `ssh`, you might want to -> run `screen` at this point, so the work won't be lost in case of a session -> drop. +> run `screen` ot `tmux` at this point, so the work won't be lost in case of a +> session drop. Build the Docker image but do not run the container: @@ -203,7 +210,7 @@ Build the Docker image but do not run the container: $ ./geniux-builder.sh [version] [manifest] [machine] -i ``` -Create an output folder and run the container: +Create an output folder and run the container with: ``` $ mkdir -p output @@ -213,6 +220,9 @@ $ docker run -it --rm \ geniux-$version:$manifest.$machine ``` +This runs the container with privileged mode, so it receives all permissions the +host has, and can create Docker images. + If you have a local mirror available, you can provide access from within the container as: @@ -225,20 +235,21 @@ $ docker run -it --rm \ geniux-$version:$manifest.$machine ``` -replacing `$my_mirror` by the actual path of your mirror and `$version` by the -actual version name you used when building the container. If you do not have any -local mirror, just omit the `-v $my_mirror:...` line. - -The build process will take several hours. At its ending, the image files will -be under your `./output` folder, so _outside_ the container. The `./output` -folder must be empty before starting the run. The container itself will be -erased after completion. +replacing `$my_mirror` by the actual path of your local mirror, and `$version` +by the actual version name you used when building the container. If you do not +have any local mirror, just omit the `-v $my_mirror:...` line. ### Interactive method +Include the `--image-only` (or `-i`) flag when invoking `geniux-builder.sh` to +skip building the Geniux images. This creates a Docker image with the necessary +environment and tools, but you'll need to build the Geniux images manually and +copy them outside the container before exiting it. This option is useful for +development or troubleshooting build failures. + > NOTE: if you are operating on a remote host through `ssh`, you might want to -> run `screen` at this point, so the work won't be lost in case of a session -> drop. +> run `screen` or `tmux` at this point, so the work won't be lost in case of a +> session drop. Build the Docker image but do not run the container: @@ -246,7 +257,9 @@ Build the Docker image but do not run the container: $ ./geniux-builder.sh [version] [manifest] [machine] -i ``` -Now run the container in the interactive mode: +Now run the container with privileged mode (so it receives all permissions the +host has) in the interactive mode. Notice the final `bash`, that will take you +to the bash console without executing the predefined commands: ``` $ mkdir -p output @@ -257,12 +270,9 @@ $ docker run -it --rm \ geniux-$version:$manifest.$machine bash ``` -replacing `$my_mirror` by the actual path of your mirror and `$version` by the -actual version name you used when building the container. If you do not have any -local mirror, just omit the `-v $my_mirror:...` line. - -**Notice the final `bash`, that will take you to the bash console without -executing the predefined commands.** +replacing `$my_mirror` by the actual path of your local mirror, and `$version` +by the actual version name you used when building the container. If you do not +have any local mirror, just omit the `-v $my_mirror:...` line. Now, inside the container, prepare the building environment: @@ -285,7 +295,19 @@ and the corresponding SDK script installer: $ bitbake -c populate_sdk gnss-sdr-dev-image ``` -For building an image with the Xfce Desktop Environment and gnss-sdr already +> Heads up! You might see warnings during those processes that look like this: +> +> ``` +> WARNING: libptytty-2.0-r0 do_fetch: Failed to fetch URL... (attempting other locations) +> WARNING: rxvt-unicode-9.31-r0 do_fetch: Failed to fetch URL... (attempting other locations) +> ``` +> +> These warnings simply mean the system couldn't download a package from the +> very first try. Don't worry, it will try alternative locations to get it. You +> can safely ignore these warnings. Only if the download fails from all +> locations will the process encounter an error. + +For building an image with the Xfce Desktop Environment and `gnss-sdr` already included: ``` @@ -305,13 +327,14 @@ be under `./build/tmp-glibc/deploy` folder. Move them to the `/home/geniux/yocto/output` folder: ``` -$ mv ./tmp-glibc/deploy/images /home/geniux/yocto/output/ -$ mv ./tmp-glibc/deploy/sdk /home/geniux/yocto/output/ +$ sudo mv ./tmp-glibc/deploy/images /home/geniux/yocto/output/ +$ sudo mv ./tmp-glibc/deploy/sdk /home/geniux/yocto/output/ ``` Now, when doing `exit` from the container, the build artifacts will be at the `./output` folder you created in your machine, so _outside_ the container. The -container itself will be erased at exit. +container itself will be erased at exit. Exiting may take some minutes, as it +erases several gigabytes of data. Please be patient and allow it to complete. ## Note for Xilinx's boards