armbian/documentation
0
0
Fork 0
mirror of https://github.com/armbian/documentation.git synced 2026-01-06 10:13:36 -08:00
Code Issues Packages Projects Releases Wiki Activity

grammar and stuff

Browse Source
This commit is contained in:
Werner
2024-10-13 19:17:23 +02:00
committed by Igor
parent 2a9b037b44
commit ce11499724
1 changed files with 23 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/Developer-Guide_Welcome.md
View File

@@ -4,31 +4,31 @@ Overview:
### (ANSI) Logging
Logs are output to `output/logs`, in a few different formats. We output ANSI color both to the screen and to the logs.
_Please_ add `SHARE_LOG=yes` to share your logs with our pastebin service when reporting issues, that allows us to check the logs on a web
browser and keep to correct formatting.
Log output is stored in `output/logs` and provided in a few different formats. ANSI coloring is applied to both the screen and the log files themselves.
_Please_ add `SHARE_LOG=yes` to automatically upload logs to our paste service and provide us with the given url when reporting issues.
That will allows us to check the logs on a web browser and keep to correct formatting.
## Command line syntax has changed
General CLI syntax: `./compile.sh PARAM=value OTHER_PARAM=other_value [<configfile> <configfile> ...] [<command>]`
- where `command` defaults to `build` if you don't specify it; could also be `kernel-config` or `u-boot` etc
- you _can't_ have a config file with the same name as a possible `<command>` (system will check & bomb if so)
- also: there's no more `default` config -- you have to be explicit
- also: there's no more `docker` config -- Docker is fully auto-managed now. The system will complain if you have one.
- you can specify `PARAM=value`, `<configfile>` or `<command>` in _any order_
- where `command` defaults to `build` if not specified; could also be `kernel-config` or `u-boot` etc...
- config file names _must not_ have the same name as a possible `<command>` (system will check & bomb if so)
- also: there is no more `default` config -- you have to be explicit
- also: there is no more `docker` config -- Docker is fully auto-managed now. The system will complain if you have one.
- parameters like `PARAM=value`, `<configfile>` or `<command>` can be applied in _any order_.
## No more `config-default.conf`, you need to specify the config file in the command line
## No more `config-default.conf`, config file name needs to be specified in the command line
- No "default" config is auto-loaded anymore. Default config lead to unreproducible failing builds and was a source of
confusion.
- The configs still go to the same place, `userpatches/config-xyz.conf` -- but now you gotta tell the build system to
use that config, like `./compile.sh BOARD=xxx xyz`; otherwise works the same.
- The configs still go to the same place, `userpatches/config-xyz.conf` -- but the name has to be provided to the build system to,
like `./compile.sh BOARD=xxx xyz`; otherwise works the same.
## Artifacts, cache, what the ...?
The `armbian/build` system is currently undergoing refactoring to improve its structure. Previously, the build system
was a single, complex Bash script that mixed the building of `.deb` packages with the creation of images.
was a single, very complex bash script that mixed the building of `.deb` packages with the creation of images.
This was reworked into a `1-to-N` image-to-artifact dependency tree; a certain image build will depend on N possible
"artifacts". Artifacts are either `.deb` packages, a `.tar` of multiple `.deb` packages, or a `rootfs.tar.zstd`. Each
@@ -36,15 +36,13 @@ artifact can be individually built, and has a specific name and a _version_.
Each artifact is also now **cached by default** using OCI storage at ghcr.io (GitHub Container Registry). To achieve
_consistent caching_, each artifact produces a version that includes _hashes_ of its composing files, variables,
patches,
hooks, external git SHA1 references, etc. That way we can consistently check the remote OCI cache for previously-built
patches, hooks, external git SHA1 references, etc. That way we can consistently check the remote OCI cache for previously-built
artifacts, and possibly save image builders from having to build heavy packages just to produce an image.
### TL-DR about artifacts and caching:
### TL;DR about artifacts and caching:
- `KERNEL_ONLY=yes` and `KERNEL_ONLY=no` are no more. Use the `kernel` CLI command instead.
- `ARTIFACT_IGNORE_CACHE=yes` can help if you're getting false positives. Please also report the problem, with a
complete logfile.
- `KERNEL_ONLY=yes` and `KERNEL_ONLY=no` are deprecated. Use the `kernel` CLI command instead.
- `ARTIFACT_IGNORE_CACHE=yes` can help with false positives. Please also report the problem, with a complete logfile.
## Automatic Docker/sudo launcher
@@ -53,11 +51,11 @@ artifacts, and possibly save image builders from having to build heavy packages
M1/M2.
- You **don't need and actually can't have the old docker config file**.
- If Docker is not installed, it will try to use `sudo` to run the build as root.
- If you run directly as root, it will warn you and ask you to run it without sudo.
- If you run directly as root, it will give a warning and asks to run without `sudo`.
## Kernel Git Trees: shallow vs full
During the build, depending on which local or remote caches are hit, it might be needed to build the Linux Kernel.
During the build, depending on which local or remote caches are hit, it might be necessary to build the Linux Kernel from scratch.
The kernel's git repo is huge. Most build systems resort to fetching "shallow" trees directly from upstream git servers,
to save bandwidth. Unfortunately that creates immense extra CPU load on the git servers. To avoid this problem,
@@ -75,9 +73,9 @@ There are two types of cached Kernel git trees:
- `shallow` is a much smaller download and requires less disk space
- `shallow` is appropriate for restricted devices like SBCs which will build a single kernel
**TL,DR: ** `KERNEL_GIT=full` or `KERNEL_GIT=shallow` or let the system decide for you.
**TL;DR: ** `KERNEL_GIT=full` or `KERNEL_GIT=shallow` or let the system decide for you.
## Consider Forking before cloning the repo
## Consider forking before cloning the repo
Before cloning the repo, consider forking it first. This will allow you to make changes and submit pull requests.
You will need a GitHub account to do this;
@@ -89,14 +87,14 @@ If you fork, make sure to keep your fork up-to-date with the main repo, by rebas
This is (by far) not a complete list:
- wifi/other kernel drivers are still using pre-armbian-next code, and are very hard to work with. it's not only the
- wifi/other kernel drivers are still using pre-armbian-next code, and are very hard to work with. it is not only the
contents are a mess, the way the whole thing works leads to more and more compounding work. To make it worse, family
patches sometimes need to patch driver code, leading to a cycle of sadness for developers. We're still coming up with
patches sometimes need to patch driver code, leading to a cycle of sadness for developers. We are still coming up with
a plan to completely replace this lest most of us go insane.
- although "aggregation" has been rewritten in Python, it still mostly works using the legacy principle, by scanning
directories and files in a very complex and error-prone way. This is a source of many bugs and confusion. We plan to
replace this with pure extensions eventually.
- we've mostly working Kernel headers (linux-headers pkg) for 5.10+ including some vendor kernels
- we have mostly working kernel headers (linux-headers pkg) for 5.10+ including some vendor kernels
## Multiple u-boot's for same board