Skip to content

Commit

Permalink
Improve instructions following Xavier Guerrero's suggestions
Browse files Browse the repository at this point in the history
  • Loading branch information
@carlesfernandez
carlesfernandez committed May 9, 2024
1 parent 0370f79 commit 3096c2d
Showing 1 changed file with 64 additions and 41 deletions.
105 changes: 64 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,16 +15,13 @@ SPDX-FileCopyrightText: 2020-2024 Carles Fernandez-Prades <carles.fernandez@cttc
The purpose of this repository is to automate the generation in a virtualized
development environment of Geniux images and their corresponding Software
Development Kit (SDK) for the cross-compilation and running of
[GNSS-SDR](https://gnss-sdr.org) on embedded systems, as well as bootable
image files that can be copied to an SD card and make your device ready to go.
[GNSS-SDR](https://gnss-sdr.org) on embedded systems, as well as bootable image
files that can be copied to an SD card and make your device ready to go.

The Docker images generated by the `Dockerfile` file of this repository can run
the building processes defined by the
[meta-gnss-sdr](https://github.com/carlesfernandez/meta-gnss-sdr) Yocto layer.

More info at:
- [Cross-compiling GNSS-SDR](https://gnss-sdr.org/docs/tutorials/cross-compiling/).

The name Geniux comes from <ins>**G**</ins>NSS-SDR for <ins>**E**</ins>mbedded
G<ins>**N**</ins>U/L<ins>**i**</ins>n<ins>**ux**</ins>.

Expand All @@ -36,7 +33,13 @@ G<ins>**N**</ins>U/L<ins>**i**</ins>n<ins>**ux**</ins>.

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 <username>
```

> Note: the `geniux-builder.sh` script makes use of the `zip` and `unzip` tools.
> On Debian/Ubuntu machines, you can install them by doing:
Expand Down Expand Up @@ -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'
Expand All @@ -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`:
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -188,22 +191,26 @@ 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:

```
$ ./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
Expand All @@ -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:

Expand All @@ -225,28 +235,31 @@ $ 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:

```
$ ./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
Expand All @@ -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:

Expand All @@ -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:

```
Expand All @@ -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

Expand Down

0 comments on commit 3096c2d

Please sign in to comment.