wbrawner/distribution
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Minor tweaks for grammar and new flow.

Browse source
This commit is contained in:
littleguy77 2023-09-03 08:36:43 -04:00
parent fbb350432d
commit b20f51edcc
1 changed files with 19 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
documentation/DEVEL_BUILDING_JELOS.md
View file

@ -6,7 +6,7 @@
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. 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.
## Preparing the Build Machine ## Preparing the Build Machine
Building JELOS requires an Ubuntu 22.04 host with 200GB of free space for a single device, or 1TB of free space for a full world build. Other Linux distributions may be used when building using Docker, however this is untested and unsupported. Building JELOS requires an Ubuntu 22.04 host with 200GB of free space for a single device, or 1TB of free space for a full world build. Other Linux distributions may be used when building using Docker; however this is untested and unsupported.
### Docker Builds ### Docker Builds
``` ```
@ -38,7 +38,7 @@ sudo apt install gcc make git unzip wget \
``` ```
## JELOS Source Files ## JELOS Source Files
To build JELOS, start by cloning the project git repository. After preparing the build machine, clone the project git repository onto it.
``` ```
cd ~ cd ~
@ -46,7 +46,7 @@ git clone https://github.com/JustEnoughLinuxOS/distribution.git
``` ```
### Selecting the Desired Branch ### Selecting the Desired Branch
Once you have cloned the repo, you will want to determine if you want to build the main branch which is more stable, or the development branch which is unstable but hosts our newest features. 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.
|Branch|Purpose| |Branch|Purpose|
|----|----| |----|----|
@ -82,7 +82,7 @@ We have a simple filesystem structure adopted from parent distributions CoreELEC
**build.JELOS-DEVICE.ARCHITECTURE** **build.JELOS-DEVICE.ARCHITECTURE**
Build roots for each device and that devices architecture(s). For ARM devices JELOS builds and uses a 32bit root for several of the cores used in the 64bit distribution. 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.
**config** **config**
@ -90,11 +90,11 @@ Contains functions utilized during the build process including architecture spec
**distributions** **distributions**
Distributions contains distribution specific build flags and parameters and splash screens. Distributions contains distribution-specific build flags and parameters and splash screens.
**Dockerfile** **Dockerfile**
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) 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).
**licenses** **licenses**
@ -106,7 +106,7 @@ Used to build one or more JELOS images, or to build and deploy the Ubuntu contai
**packages** **packages**
All of the package set that is used to develop and build JELOS are hosted within the packages directory. The package structure documentation is available in [PACKAGE.md](PACKAGE.md) 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).
**post-update** **post-update**
@ -114,7 +114,7 @@ Anything that is necessary to be run on a device after an upgrade should be adde
**projects** **projects**
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. 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.
**release** **release**
@ -126,7 +126,7 @@ This directory contains all of the scripts used to fetch, extract, build, and re
**sources** **sources**
As the distribution is being built, package source are fetched and hosted in this directory. They will persist after a `make clean`. As the distribution is being built, package source files are fetched and hosted in this directory. They will persist after a `make clean`.
**tools** **tools**
@ -158,21 +158,22 @@ make AMD64
### Rightsized Builds ### Rightsized Builds
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`. 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`.
|Build Option|Setting|Function| |Build Option|Default|Function|
|----|----|----| |----|----|----|
|EMULATION_DEVICE|yes|Builds EmulationStation and all emulators, builds EmulationStation and NO emulators if false.| |EMULATION_DEVICE|yes|Builds EmulationStation and all emulators if `yes`. Builds EmulationStation and NO emulators if `no`.|
|ENABLE_32BIT|yes|Builds a 32bit root and includes it in the image. Needed for 32bit cores and applications.| |ENABLE_32BIT|yes|Builds a 32bit root and includes it in the image. Needed for 32bit cores and applications.|
|BASE_ONLY|false<sup>1</sup>|Builds only the bare minimum packages, includes Weston on supported devices. Does not build EmulationStation.| |BASE_ONLY|false<sup>1</sup>|Builds only the bare minimum packages. Includes Weston on supported devices. Does not build EmulationStation.|
|CONTAINER_SUPPORT|no|Builds support for running containers on JELOS| |CONTAINER_SUPPORT|no|Builds support for running containers on JELOS.|
> Note: <sup>1</sup> this property will change to yes/no for consistency in a future release. > Note: <sup>1</sup> this property will change to yes/no for consistency in a future release.
### Special env Variables ### Special env Variables
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. 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.
|Variable|Function| |Variable|Function|
|----|----| |----|----|
|LOCAL_SSH_KEYS_FILE|Enables using ssh public keys for access without the root password.| |LOCAL_SSH_KEYS_FILE|Enables using ssh public keys for access without the root password.|
|LOCAL_WIFI_SSID|The SSID of the network the device should connect too automatically.| |LOCAL_WIFI_SSID|The SSID of the network the device should connect to automatically.|
|LOCAL_WIFI_KEY|The WIFI authentication key for the connection."| |LOCAL_WIFI_KEY|The WIFI authentication key for the connection."|
|SCREENSCRAPER_DEV_LOGIN|Login information for screenscraper.fr.| |SCREENSCRAPER_DEV_LOGIN|Login information for screenscraper.fr.|
|GAMESDB_APIKEY|Login information for thegamesdb.net.| |GAMESDB_APIKEY|Login information for thegamesdb.net.|
@ -215,10 +216,10 @@ It is also possible to build individual packages.
DEVICE=AMD64 ARCH=x86_64 ./scripts/clean busybox DEVICE=AMD64 ARCH=x86_64 ./scripts/clean busybox
DEVICE=AMD64 ARCH=x86_64 ./scripts/build busybox DEVICE=AMD64 ARCH=x86_64 ./scripts/build busybox
``` ```
> Note: An EmulationStation package standalone build requires additional steps because its source code located in a separate repository, see instructions inside, [link](https://github.com/JustEnoughLinuxOS/distribution/blob/main/packages/ui/emulationstation/package.mk). > 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).
### Creating a Patch for a Package ### Creating a Patch for a Package
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 built it in case you need to iterate over it. See below. 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.
``` ```
cd sources/wireguard-linux-compat cd sources/wireguard-linux-compat
@ -244,14 +245,14 @@ mkdir -p ../../packages/ui/emulationstation/patches
git diff >../../packages/ui/emulationstation/patches/005-mypatch.patch git diff >../../packages/ui/emulationstation/patches/005-mypatch.patch
``` ```
After patch is generated, one can rebuild an individual package, see section above. The build system will automatically pick up patch files from `patches` directory. For testing, one can either copy the built binary to the console or burn the whole image on SD card. 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.
### Building an Image with Your Patch ### Building an Image with Your Patch
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. 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. # Update the package version for a new package, or apply your patch as above.
vim/emacs/vscode/notepad.exe vim/emacs/vscode/notepad.exe
# Export the variables needed to complete your build, we'll assume you are building AMD64, update the device to match your configuration. # Export the variables needed to complete your build. We'll assume you are building AMD64; update the device to match your configuration.
export OS_VERSION=$(date +%Y%m%d) BUILD_DATE=$(date) export OS_VERSION=$(date +%Y%m%d) BUILD_DATE=$(date)
export PROJECT=PC ARCH=x86_64 DEVICE=AMD64 export PROJECT=PC ARCH=x86_64 DEVICE=AMD64
# Clean the package you are building. # Clean the package you are building.