====== Build Ubuntu ======

===== Introduction =====

We provide [[kg>fenix|Fenix]] to build the Ubuntu OS images easily. \\
You can follow the steps below:


===== Preparation =====

Install essential dependencies.

```shell
$ sudo apt update
$ sudo apt install git make lsb-release qemu-user-static
```

===== Get Fenix Source Code =====

Clone the Fenix repository to somewhere, e.g. ''~/project''

```shell
$ mkdir ~/project
$ cd ~/project/
$ git clone --depth 1 https://github.com/khadas/fenix
```

===== Setup the Build Environment =====

You should setup the build environment first. \\

For example: ''Board type'', ''Linux version'', ''distribution''.

```shell
$ cd ~/project/fenix
$ source env/setenv.sh
```

===== Build the OS Image =====

Just type ''make'' to start build.


<WRAP tip >
If it's the first time to build an image, the script will check your host's environment and install some essential packages. In addition, repositories (U-Boot, Linux) will be cloned automatically from the Khadas GitHub.
</WRAP>

===== Other Build Commands =====


==== Build U-Boot ====

```shell
$ make uboot
```

==== Build U-Boot Debian Package ====

```shell
$ make uboot-deb
```

==== Build Linux ====

```shell
$ make kernel
```

==== Build Linux Debian Package ====

```shell
$ make kernel-deb
```

==== Build GPU Debian Package ====

```shell
$ make gpu-deb
```

==== Build the Board Debian Package ====

```shell
$ make board-deb
```

==== Build all Debian Packages ====

```shell
$ make debs
```

==== Build U-Boot Image ====

```shell
$ make uboot-image
```

==== Clean Linux Source Tree ====

```shell
$ make kernel-clean
```

==== Show Linux Menuconfig ====

```shell
$ make kernel-config
```

==== Save Linux Defconfig ====

```shell
$ make kernel-saveconfig
```

==== Clean U-Boot Source Tree ====

```shell
$ make uboot-clean
```

==== Help Messages ====

You can get help messages by executing ''make help'':

```shell
$ make help
Fenix scripts help messages:
  all                   - Create image according to environment.
  kernel                - Build linux kernel.
  kernel-clean          - Clean linux source tree.
  kernel-config         - Show linux menuconfig.
  kernel-saveconfig     - Save linux defconfig.
  uboot                 - Build u-boot.
  uboot-clean           - Clean u-boot source tree.
  uboot-deb             - Build u-boot debian package.
  uboot-image           - Build minimal image only with u-boot.
  kernel-deb            - Build linux debian package.
  board-deb             - Build board debian package.
  common-deb            - Build common debian package.
  desktop-deb           - Build desktop debian package.
  gpu-deb               - Build gpu debian package.
  debs                  - Build all debian packages.
  image                 - Pack update image.
  clean                 - Cleanup.
  info                  - Display current environment.
  get-make-params       - Get available make parameters.
```

==== Build Options ====

Options for building:

  * ''NO_CCACHE'' - ccache option
    * ''NO_CCACHE=no make'' - Enable ccache **default** 
    * ''NO_CCACHE=yes make'' - Disable ccache 

  * ''COMPRESS_IMAGE'' - compress build image option
    * ''COMPRESS_IMAGE=no make'' - Don't compress **default**
    * ''COMPRESS_IMAGE=yes make'' - Compress image with xz

  * ''BUILD_TYPE'' - image build type option
    * ''BUILD_TYPE=develop make'' - Develop build
    * ''BUILD_TYPE=release make'' - Release build

===== Build in Docker =====

You can also choose to build the OS image in a Docker container.

==== Install Docker ====

Please refer to [[https://docs.docker.com/engine/install/|Docker Documentation]].

==== Add User to a Docker Group ====

```shell
$ sudo usermod -aG docker $USER
```

<WRAP important >
You need to logout or reboot the system to take effect.
</WRAP>


==== Check Docker ====

```shell
$ docker run hello-world
```

If you see the following print-out, Docker has installed successfully:

```txt
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
ca4f61b1923c: Pull complete
Digest: sha256:be0cd392e45be79ffeffa6b05338b98ebb16c87b255f48e297ec7f98e123905c
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://cloud.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/engine/userguide/
```

==== Build Fenix in Docker ====

Get Docker image:

```shell
$ cd ~/project/fenix
$ docker pull numbqq/fenix:latest
```

Build image in Docker:

```shell
$ docker run -it --name fenix -v $(pwd):/home/khadas/fenix \
             -v /etc/localtime:/etc/localtime:ro \
             -v /etc/timezone:/etc/timezone:ro \
             -v $HOME/.ccache:/home/khadas/.ccache --privileged \
             --device=/dev/loop-control:/dev/loop-control \
             --device=/dev/loop0:/dev/loop0 --cap-add SYS_ADMIN \
             numbqq/fenix
```
Start your build from inside the Docker container.

```shell
khadas@919cab43f66d:~/fenix$ source env/setenv.sh
khadas@919cab43f66d:~/fenix$ make
```

Restart the Docker container.

```shell
$ docker start fenix
$ docker exec -ti fenix bash
```