|
|
Please read the [build system README](https://dev.pyra-handheld.com/imagebuild/pyra-docker/blob/master/README.md) for instructions on building PyraOS from source. |
|
|
\ No newline at end of file |
|
|
# PyraOS Build System
|
|
|
|
|
|
The PyraOS build system utilizes `docker.io` to manage a clean and isolated build environment for building PyraOS images and packages.
|
|
|
|
|
|
## Setting up your host
|
|
|
|
|
|
### Installing dependencies
|
|
|
|
|
|
All you need is a Linux host, preferably x86_64 with 4+ cores and 8GB+ of RAM, with `docker.io` running. On Debian based systems, install `docker.io` via `apt`. On other systems, Google is your friend :)
|
|
|
|
|
|
```
|
|
|
sudo apt install docker.io
|
|
|
```
|
|
|
|
|
|
Note, you will probably need to add your user to the `docker` group.
|
|
|
|
|
|
```
|
|
|
sudo usermod -a -G docker $USER
|
|
|
```
|
|
|
|
|
|
Also ensure that you have an ssh key created named `id_rsa` in `~/.ssh`.
|
|
|
At this point, you will need to reboot to ensure that your user is properly associated with the `docker` group.
|
|
|
|
|
|
### Setting up your build environment
|
|
|
|
|
|
Start off by cloning the `pyra-docker` repository to a sensible build location.
|
|
|
|
|
|
```
|
|
|
git clone git@dev.pyra-handheld.com:imagebuild/pyra-docker.git /path/to/build/location
|
|
|
cd /path/to/build/location
|
|
|
```
|
|
|
|
|
|
Next, you'll need to create the directory on your host system where we'll be doing all the work. This directory will be linked into the docker environment when we start up the container.
|
|
|
|
|
|
```
|
|
|
mkdir -p /path/to/docker/directory/../build
|
|
|
```
|
|
|
|
|
|
Now we're ready to build the docker image. This will create and configure a base image of our build environment. If you're curious to see what's going on here or want to modify it, check out `Dockerfile`. Note that as long as you don't modify `Dockerfile` or `docker-entrypoint.sh` (pulling new commits from the remote counts as modifying), you only have to do this once.
|
|
|
|
|
|
```
|
|
|
./build_docker.sh
|
|
|
```
|
|
|
|
|
|
## Working with the build system
|
|
|
|
|
|
### Building a PyraOS image
|
|
|
|
|
|
Once you have the docker image built, you're ready to start using it to build a PyraOS image. Building an image consists of three steps: building U-Boot, building the rootfs from the Pyra repository (this uses the most recent stable kernel in the repo), and creating the virtual disk image.
|
|
|
|
|
|
First, sync your source repositories with the remote. This will take a fair amount of time. Note: before doing this, ensure that your git configuration is already set up. The sync will fail if it is not.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh sync-manifest
|
|
|
```
|
|
|
|
|
|
Next, build the bootloader. You must specify whether you are building for 2gb or 4gb hardware.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh build uboot [2gb|4gb]
|
|
|
```
|
|
|
|
|
|
Next, build the rootfs.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh build rootfs
|
|
|
```
|
|
|
|
|
|
Finally, create the virtual disk image. Warning: This step makes use of your host machine's loopback devices.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh build image
|
|
|
```
|
|
|
|
|
|
All binaries will be located within `build/out`. Note that the following command can be used to build everything at once, however it will build the kernel as well. The kernel built during this step is NOT the one used in the final image.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh build-all
|
|
|
```
|
|
|
|
|
|
You can also simply enter a bash shell within the docker container and run any commands manually by starting it with the following command.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh bash
|
|
|
```
|
|
|
|
|
|
### Building PyraOS Debian packages
|
|
|
|
|
|
Coming soon!
|
|
|
|
|
|
### Building DBPs
|
|
|
|
|
|
Coming soon!
|
|
|
|
|
|
## Contributing to PyraOS
|
|
|
|
|
|
Please contribute! PyraOS is a community driven project, so we are doing everything we can to make it easy and safe for the community to provide contributions to source code. The PyraOS build system tracks all OS and build system source code in `git` which makes contribution simple. However, there are a few rules set in place to make sure everything stays clean and organized.
|
|
|
|
|
|
### Creating merge requests
|
|
|
|
|
|
In order to maintain a clean and stable working history within the git repositories, contributors are NOT allowed to push directly to protected branches. You can check the remote to see which branches are protected, but typically `master` will always be protected.
|
|
|
|
|
|
Before making changes to the code, first check the remote to see if there is currently a merge request out for the given issue. If there is, great! Just make comments on the given merge request to help the contributor currently working on it. Otherwise, ensure that you first checkout the main development branch. `repo` checks out commits in a detached state, so make sure you are not branching off of the main development branch. If other commits are merged before feature branch is, you must rebase your feature branch on top of the main development branch before it can be merged.
|
|
|
|
|
|
Next, create a feature branch with the following name structure `\<forum-handle\>/\<[feature|fix]\>/\<branch-name\>`. For example, `toastbucket/fix/update-twl6040-register-map`. Make your commits on this branch and push to the remote with the following command. To get the name of the remote, run `git remote -v`. Note that you do not need to perform git operations from within the docker environment.
|
|
|
|
|
|
```
|
|
|
git push -u <remote-name> <branch-name>
|
|
|
```
|
|
|
|
|
|
Once your commit has been pushed, create a merge request on the remote by logging in on a browser and navigating to the repository. Click on `Merge Requests` on the left sidebar. You should see a button at the top for creating a merge request.
|
|
|
|
|
|
### Coding style requirements
|
|
|
|
|
|
One of the main goals of PyraOS/LetuxOS is to push changes back to mainline. This helps maintain support for the Pyra in future kernel revisions. Because of this, coding style of contributions is important in order to prevent rejection during review from mainline maintainers. Please read up on the following coding guidelines before pushing any features or fixes.
|
|
|
|
|
|
Linux coding style: https://www.kernel.org/doc/html/v4.17/process/coding-style.html
|
|
|
|
|
|
U-Boot coding style: https://www.denx.de/wiki/U-Boot/CodingStyle |
|
|
\ No newline at end of file |