******************* 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 `_. 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 `_ and you can access `the core-os repository `_. 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 `_ 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/ You have to replace `` by the name of your SD Card device.