canoeboot
/
cbwww
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

another tweak to docs/maintain/ 

this doesn't actually add missing information, but does make
existing information clearer.

it's always the case that when i'm running a release build, i
immediately notice everything wrong with it.

i'm not stopping the build!

Signed-off-by: Leah Rowe <info@minifree.org>
master
Leah Rowe 2024-12-06 00:11:31 +00:00
parent 7f71d26555
commit aeb1a3aebb
1 changed files with 37 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
site/docs/maintain/index.md
View File

@ -119,18 +119,18 @@ The files under `bin/` are provided in regular Canoeboot releases.
**These** are the ROM images that you should flash. **These** are the ROM images that you should flash.
Older versions of lbmk build coreboot images separately under `elf/`, but Older versions of cbmk build coreboot images separately under `elf/`, but
without payloads, using `elf/` as a build cache, then inserting payloads without payloads, using `elf/` as a build cache, then inserting payloads
into copies of these images in files under `bin/`. However, modern lbmk into copies of these images in files under `bin/`. However, modern cbmk
now only puts coreboot images in `bin/`, with payloads included. now only puts coreboot images in `bin/`, with payloads included.
If you still have `elf/` coreboot images in your lbmk tree, please do not If you still have `elf/` coreboot images in your cbmk tree, please do not
use them (and you may aswell delete them). use them (and you may aswell delete them).
cache/ cache/
--------------- ---------------
Certain files are cached here automatically, by lbmk. The user need not touch Certain files are cached here automatically, by cbmk. The user need not touch
these files. these files.
cache/app cache/app
@ -155,12 +155,12 @@ run `git submodule update` commands when handling Git repositories anymore,
instead processing submodules manually; it supports both repositories *and* instead processing submodules manually; it supports both repositories *and*
files relative to the directory locations for those repositories, but subfiles files relative to the directory locations for those repositories, but subfiles
are not downloaded to the *cached git repository*, only the work directory used are not downloaded to the *cached git repository*, only the work directory used
for building in lbmk. for building in cbmk.
cache/hash cache/hash
--------------- ---------------
When lbmk is handling any project, it sorts a list of files under `config/` When cbmk is handling any project, it sorts a list of files under `config/`
including `config/project` (or `config/project/TREE`) and `config/data/project`. including `config/project` (or `config/project/TREE`) and `config/data/project`.
SHA512 checksums are calculated from these files, in the sorted order, and SHA512 checksums are calculated from these files, in the sorted order, and
@ -181,7 +181,7 @@ elf/
--------------- ---------------
**DO NOT flash coreboot ROM images contained under `elf/`. Please use ROM images **DO NOT flash coreboot ROM images contained under `elf/`. Please use ROM images
under `bin/` instead! - In modern lbmk, only the ones under `bin/` are ever under `bin/` instead! - In modern cbmk, only the ones under `bin/` are ever
created anyway.** created anyway.**
Compiled binaries (compiled by cbmk) go here, but they are not the final Compiled binaries (compiled by cbmk) go here, but they are not the final
@ -197,13 +197,13 @@ operation, to `elf/PROJECT` for single-tree projects,
or `elf/PROJECT/TREE` for multi-tree projects. or `elf/PROJECT/TREE` for multi-tree projects.
It is technically possible to re-use these files elsewhere. For example, you It is technically possible to re-use these files elsewhere. For example, you
may wish to only compile GRUB with lbmk, and then use the `grub.elf` file from may wish to only compile GRUB with cbmk, and then use the `grub.elf` file from
cbmk in your own custom coreboot ROM (that you didn't build with lbmk). However, cbmk in your own custom coreboot ROM (that you didn't build with cbmk). However,
this use is not officially supported by the Canoeboot project; these files are this use is not officially supported by the Canoeboot project; these files are
simply used by the Canoeboot build system. simply used by the Canoeboot build system.
Some utilities are also provided compiled here, when building. For Some utilities are also provided compiled here, when building. For
example: `elf/flashprog/flashprog`. This is because lbmk tries to provide example: `elf/flashprog/flashprog`. This is because cbmk tries to provide
out-of-source builds whenever feasible. out-of-source builds whenever feasible.
This is only used by the build system, but these images are *not* provided in This is only used by the build system, but these images are *not* provided in
@ -384,7 +384,7 @@ provides UEFI. Information about that can be found on these resources:
This is currently the only payload on *ARM* systems, within Canoeboot. This is currently the only payload on *ARM* systems, within Canoeboot.
U-Boot is also available on x86 machines, since the Libreboot 20241205 release. U-Boot is also available on x86 machines, since the Canoeboot 20241207 release.
More information can be found on the [U-Boot x86 page](../install/uboot-x86.md); More information can be found on the [U-Boot x86 page](../install/uboot-x86.md);
it is available as an alternative to the traditional SeaBIOS and GRUB payloads, it is available as an alternative to the traditional SeaBIOS and GRUB payloads,
and it can successfully boot UEFI applications on x86 Canoeboot systems. and it can successfully boot UEFI applications on x86 Canoeboot systems.
@ -574,7 +574,29 @@ as:
* `release="n"` (example entry) * `release="n"` (example entry)
* `xtree="default"` (example entry) * `xtree="default"` (example entry)
* `tree_depend="default"` (example entry) * `tree_depend="default"` (example entry)
* `grubtree="nvme"` (example entry) * `grubtree="nvme" (example entry)`
* `payload_uboot_i386="y"` (example entry - 32 bit U-Boot)
* `payload_uboot_amd64="y"` (example entry - 64 bit U-Boot)
Please also check the `build_depend` variable
in `config/data/coreboot/mkhelper.cfg` - and compare to what trees are used
for payloads in the given target. If your board's `target.cfg` requires trees
and projects other than that specified in `mkhelper.cfg`, you must replace
the entire `build_depend` string. For example, if your board requires GRUB with
xHCI patches, with SeaBIOS and with U-Boot AMD64, and you also want memtest86plus,
you would therefore set the string as follows:
```
build_depend="grub/xhci seabios/default u-boot/amd64coreboot memtest86plus"
```
In the above example, you would also set `grubtree="xhci"`,
but please note that there is only one SeaBIOS tree so `/default` is implied,
but must still be in the `build_depend` variable. Multiple U-Boot trees exist,
but for x86 32-bit you would only specify `i386coreboot` and for 64-bit you
would only specify `amd64coreboot` and for ARM64 you say `default` - so you
do not need to specify a `seabiostree` or `uboottree` variable, and these are
not handled, because cbmk simply assumes use of the aforementioned tree names.
The `tree` value refers to `config/coreboot/TREE`; in other words, a given The `tree` value refers to `config/coreboot/TREE`; in other words, a given
target could specify a name other than its own as the tree; it would then target could specify a name other than its own as the tree; it would then
@ -762,7 +784,7 @@ for any single- or multi-tree project. Arguments available are as follows:
You can define anything else here, for use by a given project. More specifically, You can define anything else here, for use by a given project. More specifically,
anything you put in mkhelper files will be imported as part of a normal shell anything you put in mkhelper files will be imported as part of a normal shell
script during operation of lbmk, to complement core functionality across all script during operation of cbmk, to complement core functionality across all
the various projects. the various projects.
The `mkhelper` file is a global configuration for the project. Individual The `mkhelper` file is a global configuration for the project. Individual
@ -771,10 +793,10 @@ each project, project tree or target on a given multi-tree project.
The `mkhelper` functionality (and postmake/premake) was originally implemented The `mkhelper` functionality (and postmake/premake) was originally implemented
so that lots of special configuration could be done per project, without a lot so that lots of special configuration could be done per project, without a lot
of code repetition. This is a unique design of lbmk, different from many other of code repetition. This is a unique design of cbmk, different from many other
coreboot-distro build systems. coreboot-distro build systems.
The `mkhelper` functionality is an essential component that makes lbmk work The `mkhelper` functionality is an essential component that makes cbmk work
the way it does; for example, the `trees` script builds coreboot images without the way it does; for example, the `trees` script builds coreboot images without
payloads, and functions to add payloads are handled by mkhelper-type functions. payloads, and functions to add payloads are handled by mkhelper-type functions.
This design allows almost all functionality to be centralised, where the mkhelper This design allows almost all functionality to be centralised, where the mkhelper