*******************
Core OS Quick Build
*******************

Welcome!
########

This short document will help you generate your first image for any device
supported by CoreOS. If you are familiar with Yocto, this chapiter was
inspired and is structured in the same way as the `Yocto Project Quick Build
documentation <https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html>`_.

Compatible Build Machine
########################

Building a whole operating system from scratch takes a long time and requires
a powerful build machine.

We recommend to have at least:

* A modern CPU with at least 6-cores (Intel i7 9th generation or equivalent)
* A fast SSD for the operating system
* 32GB of RAM

Optionally, for better performance you should use a separate SSD used only by
the Yocto build system.

Compatible Linux Distribution
#############################

At this moment, the CoreOS system is only tested on `Debian 11` build
machines and it's the recommended operating system for new user. This
documentation assumes that you have a machine running natively with it.

Before starting, you should ensure that you have at least 250GB of free disk
space.

Package needed on the build machine
###################################

Theses packages are needed on your build machine:

.. code-block:: sh

   ~$ sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential \
      chrpath socat cpio python3 python3-pip python3-pexpect xz-utils \
      debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa \
      libsdl1.2-dev pylint3 xterm python3-subunit mesa-common-dev zstd \
      liblz4-tool bmap-tools efitools openssl sbsigntool python3-click \
      python3-aiohttp

Use Git to clone CoreOS
########################

.. hint::

   If you read this documentation, you probably already have an account on
   `BitBucket <bitbucket.gad.local>`_ and you can access `the core-os repository
   <https://bitbucket.gad.local/projects/ICO/repos/coreos/browse>`_. Otherwise you should
   ask the person who sent you a copy of this document.

To clone the repository, you have to add an SSH key to your BitBucket account via
`the BitBucket SSH Key configuration page <https://bitbucket.gad.local/plugins/servlet/ssh/account/keys>`_
first.

.. code-block:: sh

   ~$ git clone --recurse-submodules ssh://git@bitbucket.gad.local:7999/ico/coreos.git
   ~$ cd coreos

Building an image
#################

Before building an image, we have to first configure the build.

To create a build folder with our default configuration, you can run the
`coreos-init-build-env` script:

.. code-block:: sh

   ~/core-os$ source coreos-init-build-env

.. note::

    The inilization script has created a `build` directory inside the `core-os` directory and
    copied some default configuration in the `build/conf` folder. The current working directory
    was changed and we are now inside `~/coreos/build`

You can open the `build/conf/local.conf` file to change the build configuration. You probably
want to change the current `MACHINE` to one that is compatible with the hardware that you want
to build an image for.

Now that you have configured the build, we can build an `image`. Building an `image` will
generate a bootable disk image that can be used to boot the system. This document assume that
the machine is set to `cn9130-cf-pro` but you can use any other MACHINE listed in local.conf.

.. hint::

    If you use another machine that `cn9130-cf-pro`, you will have to replace each
    occurrences of `cn9130-cf-pro` to your machine when executing a command.

For an image that contains a lot of developer tools, the best image to build
is `coreos-image-all-features`.

.. code-block:: sh

   ~/img-build/build$ bitbake coreos-image-all-features

After a long time, the build system will return. You can list all the artifacts
produced by `bitbake` using `ls`:

.. code-block:: sh

   ~/coreos/build$ ls tmp/deploy/images/*/

A lot of file was generated, but the file that you can flash to your SD Card can
be found with this command:

.. code-block:: sh

   ~/coreos/build$ find tmp/deploy/images/${MACHINE} -type l -name "*.wic.xz"
   tmp/deploy/images/cn9130-cf-pro/coreos-image-all-features-cn9130-cf-pro.wic.xz

.. hint::

   Note that `bitbake` generates a lof of symlinks so that the same file can be
   accessed using multiple filenames.

Flashing an image to a SD Card
##############################

.. warning::

   Flashing an image to the wrong disk can remove all your file

The safest way to get the name of your SD card disk is to first run this
command before inserting the SD Card into your computer:

.. code-block:: sh

   ~/coreos/build$ lsblk | grep disk | grep mmc

This command should return nothing. If it does, do not use any of the disk name
listed.

Now insert the SD card in your computer and rerun the same command:

.. code-block:: sh

   ~/coreos/build$ lsblk | grep disk | grep mmc
   mmcblk0            179:0    0  14.8G  0 disk

You should have a single line printed. The name of your SD card device is the
first word printed, here `mmcblk0`. If you have multiple printed, take the name
from the single line that was not present the first time you have run the
command.

.. hint::

   If you are unsure, you can also check that the disk size match the one of
   your SD Card. I have inserted a 16GB sdcard, and the command report a size of
   of 14.8G, so this is a match. The command report the size in GiB, you can use
   google to convert GiB to GB, just search "14.8GiB in GB" and expect some
   rounding error.

Now, flash the image file to the your card:

.. code-block:: sh

   ~/coreos/build$ bmaptool copy tmp/deploy/images/cn9130-cf-pro/coreos-image-all-features-cn9130-cf-pro.wic.xz /dev/<DISKNAME>

You have to replace `<DISKNAME>` by the name of your SD Card device.
