Skip to content

Commit 73a0c9e

Browse files
jameswalmsleyjameswalmsley
committed
[DOCS] Updated index.
1 parent e93ec62 commit 73a0c9e

File tree

1 file changed

+126
-15
lines changed

1 file changed

+126
-15
lines changed

‎docs/index.md

Lines changed: 126 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,138 @@
22

33
VE-ROOT is an embedded rootfs build tool.
44

5-
## Commands
5+
# Repository
66

7-
* `make info` - List all layers in the configured recipe.
8-
* `make git.pull` - Pull all git repos from all layers.
7+
| Location | Description |
8+
| ---------- | --------------------------------------------------- |
9+
| `Makefile` | top-level ve-root Makefile |
10+
| `mk/*.mk` | Internal ve-root scripts, e.g. $(DEFINE_RECIPE) ... |
11+
| `docs` | Documentation. |
12+
| `configs` | A cache of defconfig files. |
13+
| `layers` | Generic layers for use in recipes. |
14+
| `recipes` | Build recipes. |
15+
| `sources` | Source checkout folder |
16+
| `out` | Build output folder. |
917

10-
## Build Output
18+
# Build System
1119

12-
mkdocs.yml # The configuration file.
13-
docs/
14-
index.md # The documentation homepage.
15-
... # Other markdown pages, images and other files.
20+
The build system works using a structure of recipes, built from layers, containing tasks.
1621

17-
## Variables
22+
* A recipe describes how to build an entire system - an ordered list of layers.
23+
* Layers within the recipe describe how to build each 'component'.
24+
* Each layer consists of many 'Make' tasks to generate the layer outputs.
25+
26+
The dependency graph is managed at the layer level.
27+
Layers are responsible for managing their own internal dependencies.
28+
29+
```note
30+
It is highly recommend to remain within the recipe/layer model. Deviating from
31+
this design pattern will result in unreliable builds and difficult dependency issues.
32+
```
33+
34+
!!NOTE!! Before building any recipe, complete a source-checkout first:
35+
36+
```
37+
make -j4 source-checkout
38+
```
39+
40+
Some recipes may rely on source code (e.g. git revisions etc) to generate internal variables.
41+
42+
# Recipes
43+
44+
## Variants
45+
Recipe configurations can define multiple variants.
46+
To define a variant simply define CONFIG_VARIANT in a config file:
47+
48+
```
49+
CONFIG_VARIANT:=jetson-tx2
50+
```
51+
52+
Defining a variant will ensure that all sources, and build outputs are kept separate from each other.
53+
This allows easy switching between configurations and prevents 'stale' or mixed builds.
54+
55+
## Layers
56+
57+
# Source Code Management
58+
59+
Layers define all the sources they require using the git_clone and get_archive functions.
60+
61+
| Function | Example | Description |
62+
| ----------- | -------------------------------------------------------- | -------------------------------- |
63+
| git_clone | $(call git_clone, checkout-dir, git-url, tag/branch/ref) | Clones a git repo. |
64+
| get_archive | $(call get_archive, checkout-dir, url) | Fetches and extracts an archive. |
65+
66+
These will be cloned and downloaded using `make source-checkout`.
67+
68+
## Checkout Path
69+
70+
```
71+
sources/$(RECIPE)/{$(VARIANT)}/L_$(LAYER)/checkout-dir
72+
```
73+
74+
Individual tasks can access the sources through the variables:
75+
76+
```
77+
$(srcdir)/checkout-dir # Task context only (runtime).
78+
$(SRC_layer-name)/checkout-dir # Globally
79+
```
80+
81+
# Build Management
82+
83+
Similar to source management, all builds are found under:
84+
85+
```
86+
OUT:=out/$(RECIPE)/{$(VARIANT)}/
87+
$(OUT)/build/L_$(LAYER)/
88+
$(OUT)/rootfs
89+
...
90+
```
91+
92+
A layer's build path is accessible through the following variables:
93+
94+
```
95+
$(builddir)/
96+
$(BUILD_layer-name)/
97+
```
98+
99+
# Commands
100+
101+
| Command | Description |
102+
| --------------------------- | -------------------------------------------- |
103+
| `make info` | List all layers in the configured recipe. |
104+
| `make source-checkout` | Clone and download all sources. |
105+
| `make docker` | Enter the docker container. |
106+
| `make docker.build` | Build the configured docker container. |
107+
| `make chroot` | Enter a chroot jail of the generated rootfs. |
108+
| `make git.pull` | |
109+
| `make git.checkout` | |
110+
| `make git.fetch` | |
111+
| `make git.submodule.update` | |
112+
| `make git.unshallow` | |
113+
| `make git.rev-parse.head` | |
114+
| `make git.status` | |
115+
| | |
116+
117+
118+
# Variables
119+
120+
| Name | Default | Context | Description |
121+
| ------------------- | ------------------------- | --------- | ------------------------------------------ |
122+
| $(L) | `$(LAYER)` | Parse | |
123+
| $(RECIPE) | `recipes/recipe_name` | | The actual RECIPE the layer is defined in. |
124+
| $(TOP) | `recipes/top_recipe_name` | | The absolute TOP layer. |
125+
| $(BUILD) | `$(OUT)/build` | | |
126+
| $(builddir) | `$(BUILD)/$(L)` | Make task | Equivalent to $(BUILD)/$(L)/ |
127+
| $(BUILD_layer-name) | `$(BUILD)/layer-name` | Global | |
18128

19-
| Name | Default | Context | Description |
20-
| ----------- | ------------------- | ------- | ---------------------- |
21-
| $(L) | Current layer name. | Parse | |
22-
| $(RECIPE) | | | |
23-
| $(BUILD) | | | |
24-
| $(builddir) | | Runtime | Equivalent to $(BUILD) |
25129

26130

27131
## Layer Commands
28132

133+
## Layer Variables
134+
LAYER:
135+
LAYER_NODEPEND_FILE:
136+
137+
138+
# Template System
139+

0 commit comments

Comments
 (0)