JELOS is a fairly unique distribution as it is *built to order* and only enough of the operating system and applications are built for the purpose of booting and executing emulators and ports. Developers and others who would like to contribute to our project should read and agree to the [Contributor Covenant Code of Conduct](https://github.com/JustEnoughLinuxOS/distribution/blob/main/CODE_OF_CONDUCT.md) and [Contributing to JELOS](https://github.com/JustEnoughLinuxOS/distribution/blob/main/CONTRIBUTING.md) guides before submitting your first contribution.
**Docker is the easiest and most reliable way to build JELOS.** You need no previous experience with Docker; you merely need to install it on your build machine. Newcomers to the project are strongly recommended to use this approach.
We recommend using Ubuntu 22.04 for the host machine, as this is well-tested and known to work. Other distributions and operating systems might also work for Docker builds, but are untested and unsupported.
> Docker installation reference (source): [Install using the apt repository](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository) and [Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/).
The final command should produce a message indicating that Docker is properly installed. If you encounter any errors, see the reference links above.
Manual builds (outside of Docker) are only recommended for developers with specific needs that cannot be met by the Docker approach. The host configuration should match the Docker container as closely as possible, running Ubuntu 22.04 with all packages listed in the [Dockerfile](../Dockerfile).
Once you have cloned the repo, decide whether you want to build the main branch which is more stable, or the development branch which is unstable but hosts our newest features.
Build roots for each device and that device's architecture(s). For ARM devices JELOS builds and uses a 32bit root for several of the cores used in the 64bit distribution.
Contains functions utilized during the build process including architecture specific build flags, optimizations, and functions used throughout the build workflow.
Used to build the Ubuntu container used to build JELOS. The container is hosted at [https://hub.docker.com/u/justenoughlinuxos](https://hub.docker.com/u/justenoughlinuxos).
All of the licenses used throughout the distribution packages are hosted here. If you're adding a package that contains a license, make sure it is available in this directory before submitting the PR.
**Makefile**
Used to build one or more JELOS images, or to build and deploy the Ubuntu container.
All of the packages used to develop and build JELOS are hosted within the packages directory. The package structure documentation is available in [DEVEL_CREATING_PACKAGES.md](DEVEL_CREATING_PACKAGES.md).
Anything that is necessary to be run on a device after an upgrade should be added here. Be sure to apply a guard to test that the change needs to be executed before execution.
Hardware-specific parameters are stored in the projects folder. Anything that should not be included on every device during a world build should be isolated to the specific project or device here.
The tools directory contains utility scripts that can be used during the development process, including a simple tool to burn an image to a usb drive or sdcard.
Building JELOS is easy, the fastest and most recommended method is to instruct the build to use Docker, this is only known to work on a Linux system. To build JELOS with Docker use the table below.
JELOS supports various build variables which alter the behavior of the distribution for specific purposes including debugging, or hosting containers. The options are defined below and are passed on the make command line. Ex. `BASE_ONLY=true make docker-RK3566`.
For development builds, you can use the following env variables to customize the image or change build time functionality. To make them globally available to the builds, add them to ${HOME}/.JELOS/options.
#### Screenscraper, GamesDB, and RetroAchievements
To enable Screenscraper, GamesDB, and RetroAchievements, register at each site and apply the api keys in ${HOME}/.JELOS/options. Unsetting one of the variables will disable it in EmulationStation. This configuration is picked up by EmulationStation during the build.
```
# Apply for a Screenscraper API Key here: https://www.screenscraper.fr/forumsujets.php?frub=12&numpage=0
> Note: An EmulationStation package standalone build requires additional steps because its source code is located in a separate repository. See instructions [here](https://github.com/JustEnoughLinuxOS/distribution/blob/main/packages/ui/emulationstation/package.mk).
It is common to have imported package source code modifed to fit the use case. It's recommended to use a special shell script to build it in case you need to iterate over it. See below.
After the patch is generated, rebuild an individual package by following the section above. The build system will automatically pick up patch files from the `patches` directory. For testing, one can either copy the built binary to the console or burn the whole image on SD card.
If you already have a build for your device made using the above process, it's simple to shortcut the build process and create an image to test your changes quickly using the process below.
```
# Update the package version for a new package, or apply your patch as above.
