|
| 1 | +# Building |
| 2 | + |
| 3 | +## Project configuration |
| 4 | +A configuration is the list of modules and their parameters on the one side, and set of requirements to system functionality on the other. Check the "Modular structure of Embox" section for more details. The current configuration is in the files of "conf/" directory. |
| 5 | + |
| 6 | +## Choice of configuration |
| 7 | +To set the configuration with desired properties, it's necessary to describe these properties in the "conf/" directory. But if the similar configuration is already exists, it'll be more easy for you to use the existing description as a base for making your own configuration. |
| 8 | + |
| 9 | +You can see the existing configuration, using the next command: |
| 10 | +``` |
| 11 | + $ make confload |
| 12 | +``` |
| 13 | +After it's possible to load the chosen configuration the next way: |
| 14 | +``` |
| 15 | + $ make confload-<template> |
| 16 | +``` |
| 17 | +To pay attention: after running the "make confload-", your "conf/" directory will have files of chosen configuration. And files, that were in this directory before will be deleted. |
| 18 | + |
| 19 | +In the next example we choose the existing "platform/quake3/qemu" configuration from the list: |
| 20 | +``` |
| 21 | + $ make confload |
| 22 | + List of available templates: |
| 23 | + ... |
| 24 | + platform/quake3/qemu |
| 25 | + ... |
| 26 | + Use 'make confload-<template>' to load one. |
| 27 | +
|
| 28 | + $ make confload-platform/quake3/qemu |
| 29 | +``` |
| 30 | + |
| 31 | +## Building made of existing configuration |
| 32 | +To build the image, it's necessary to set the chosen configuration as a current one how it was shown in the previous example. And then to run: |
| 33 | +``` |
| 34 | + $ make |
| 35 | +``` |
| 36 | +If everything is correct, you'll see the "Build complete" message. Also the ELF-file of the image will appear in the "build/base/bin/embox" path. |
| 37 | + |
| 38 | +For instance: |
| 39 | +``` |
| 40 | + text data bss dec hex filename |
| 41 | + 1259425 248540 170593504 172101469 a420f5d build/base/bin/embox |
| 42 | + Build complete |
| 43 | +``` |
| 44 | + |
| 45 | +## Changing system characteristics |
| 46 | +After selection of configuration you can change it, using "conf/" file. We remind you: if to run "make confload-" or make cleaning, that connected with current configuration (e. g. "make distclean"), current changes will be lost. |
| 47 | + |
| 48 | +### Changing system functionality |
| 49 | +#### Modification of the modules list |
| 50 | +"Mods.conf" file contains a description of system functionality, so you should use this file if you want to change functionality. For example, to add a new command to the list, it's necessary to insert to "mods.conf" file the next line: |
| 51 | +``` |
| 52 | + include <PACKAGE_NAME>.<MODULE_NAME> |
| 53 | +``` |
| 54 | +For instance: |
| 55 | +``` |
| 56 | + include embox.cmds.help |
| 57 | +``` |
| 58 | +The same way also works in case of standard modules. |
| 59 | + |
| 60 | +#### Module parameters |
| 61 | +To set size of thread stack, you need to change (or to add) the *thread_stack_size* parameter in the *embox.kernel.thread.core* module: |
| 62 | +``` |
| 63 | + include embox.kernel.thread.core(thread_stack_size=0x4000) |
| 64 | +``` |
| 65 | + |
| 66 | +#### Load order |
| 67 | +You can manage the order, in which the modules of system load in configuration. Use the «@Runlevel(level)» (e. g. *@Runlevel(2)*) attribute for this purpose, but usually it's not required, because modules are loading according to dependencies (if some module *B* depends on some module *A*, then *A* will be loaded before *B*). |
| 68 | + |
| 69 | + |
| 70 | +#### Changing of interface implementation |
| 71 | +To change interface implementation (that is the same as abstraction module; see "The modular structure of Embox" section for more details), you need just to add a module of this interface to your configuration. |
| 72 | + |
| 73 | +For example, the abstract module *heap_api*: |
| 74 | +``` |
| 75 | + @DefaultImpl(heap_bm) |
| 76 | + abstract module heap_api { |
| 77 | + ... |
| 78 | + } |
| 79 | +``` |
| 80 | +To add the *heap_simple* module, |
| 81 | +``` |
| 82 | + module heap_simple extends heap_api {module heap_simple extends heap_api { |
| 83 | + ... |
| 84 | + } |
| 85 | +``` |
| 86 | +it's necessary to delete *heap_bm* module (if you have it), that is the same as the next line: |
| 87 | +``` |
| 88 | + include embox.mem.heap_bm |
| 89 | +``` |
| 90 | +and then to do: |
| 91 | +``` |
| 92 | + include embox.mem.heap_simple |
| 93 | +``` |
| 94 | + |
| 95 | +### Changing flags of compilation (debugging, optimization) |
| 96 | +You can manage some flags of compilation. The "conf/build.conf" has them. For example, flag of optimization (that often requires to make changes): |
| 97 | +``` |
| 98 | + CFLAGS += -O0 |
| 99 | +``` |
| 100 | +To build the Embox with optimization 2, you should the line above to the next one: |
| 101 | +``` |
| 102 | + CFLAGS += -O2 |
| 103 | +``` |
| 104 | +Also another important flag is the *-g* linker flag, that is the same as adding debugging information in system image: |
| 105 | +``` |
| 106 | + LDFLAGS += -N -g |
| 107 | +``` |
| 108 | +You can delete this flag for size reduction, but in this case the debugging will be unavailable. |
| 109 | + |
| 110 | +## Cleaning the project |
| 111 | +Embox building has several stages. The main of them are: |
| 112 | + |
| 113 | +* Project configuration |
| 114 | +* Creating modules dependency graph and using it for generation of artifacts for building |
| 115 | +* Building itself (compilation, linking) |
| 116 | + |
| 117 | +You can reset (clean) the project to different stages of building. The are the next three make-goals for this purpose: |
| 118 | + |
| 119 | +* make distclean |
| 120 | +* make cacheclean |
| 121 | +* make clean |
| 122 | + |
| 123 | +The *clean*-goal just deletes "build" directory with objects and binary files. It's enough for most cases. |
| 124 | + |
| 125 | +The *cacheclean*-goal also deletes "build" directory as the previous goal, but in addition *cacheclean* also deletes "mk/.cache" directory,that contains artifacts from Mybuild-files. |
| 126 | + |
| 127 | +The *distclean*-goal resets the project to its original state. That is deleting the working configuration, cleaning all generated and compiled files. |
| 128 | + |
| 129 | +## Useful commands |
| 130 | + |
| 131 | +### Information about commands of building |
| 132 | +You can get more information about feachures of command line, using: |
| 133 | +``` |
| 134 | + $ make help |
| 135 | +``` |
| 136 | +There are different subsections of the *help* goal, for example, *help-mod*: |
| 137 | +``` |
| 138 | + $ make help-mod |
| 139 | +``` |
| 140 | +To get more information about modules management you can the next way: |
| 141 | +``` |
| 142 | +Usage: make mod-<INFO> |
| 143 | +
|
| 144 | + Print <INFO> info about modules: |
| 145 | + list: list all modules included in build |
| 146 | + brief-<module_name>: show brief informataion about module: dependencies, options, |
| 147 | + source files |
| 148 | + include-reason-<module_name>: show dependence subtree desribing why <module_name> |
| 149 | + was included in build |
| 150 | +``` |
| 151 | + |
| 152 | +### Getting disassembler of current image |
| 153 | +You can get the file with disassembler, using the command below: |
| 154 | +``` |
| 155 | + $ make disasm |
| 156 | +``` |
| 157 | + |
| 158 | +### Getting the graph of modules |
| 159 | +The command below will allow you to get graph of modules in png-format: |
| 160 | +``` |
| 161 | + $ make dot |
| 162 | +``` |
| 163 | +После выполнения команды *$ make dot* появится файл *build/doc/embox.png*.After running *make dot* command the *build/doc/embox.png* will appear. |
| 164 | + |
| 165 | +You'll need to install the *graphviz* package: |
| 166 | +``` |
| 167 | + $ sudo apt install graphviz |
| 168 | +``` |
| 169 | + |
| 170 | +### Getting documentation from doxygen-comments |
| 171 | +To generate docs based on doxygen-comments, you can do: |
| 172 | +``` |
| 173 | + $ make docsgen |
| 174 | +``` |
| 175 | +After running the command above the *build/docs/html* directory, that has generated html-documentation, will appear. |
| 176 | + |
| 177 | +Also you'll need to install the *doxygen* package: |
| 178 | +``` |
| 179 | + $ sudo apt install doxygen |
| 180 | +``` |
| 181 | + |
| 182 | +### Modules management |
| 183 | +To get the list of all modules, that are in the current configuration, it's necessary to run: |
| 184 | +``` |
| 185 | + $ make mod-list |
| 186 | +``` |
| 187 | + |
| 188 | +You can get more details about every module. For instance, you can get the information about *embox.net.route* module, using the next command: |
| 189 | +``` |
| 190 | + $ make mod-brief-embox.net.route |
| 191 | +``` |
| 192 | +You'll get the next output as a result: |
| 193 | +``` |
| 194 | + --- embox.net.route --- |
| 195 | + Inclusion reason: as dependence |
| 196 | + Depends: |
| 197 | + embox.net.core |
| 198 | + embox.mem.pool_ndebug |
| 199 | + embox.util.DListDebug |
| 200 | + Dependents: |
| 201 | + embox.cmd.net.ping |
| 202 | + embox.cmd.net.route |
| 203 | + embox.net.af_inet |
| 204 | + embox.net.ipv4 |
| 205 | + embox.net.tcp_sock |
| 206 | + OptInsts: |
| 207 | + route_table_size : 8 |
| 208 | + Sources: |
| 209 | + src/net/l3/route.c |
| 210 | +``` |
| 211 | +From the output above you can get information about: |
| 212 | + |
| 213 | +* list of files, that are in some modules |
| 214 | +* options, that have established values |
| 215 | +* the reason of switching-on some module and dependencies of this module |
| 216 | + |
| 217 | +Sometimes you need to define: "Why does one or other module switch-on"? For this purpose you can use: |
| 218 | +``` |
| 219 | + make include-reason-<module_name> |
| 220 | +``` |
| 221 | +We used the *embox.net.route* module to demonstrate how this command works: |
| 222 | +``` |
| 223 | + $ make mod-include-reason-embox.net.route |
| 224 | + embox.net.route: as dependence: |
| 225 | + embox.cmd.net.ping: explicit |
| 226 | + embox.cmd.net.route: explicit |
| 227 | + embox.net.af_inet: explicit |
| 228 | + embox.net.ipv4: explicit |
| 229 | + embox.net.tcp_sock: explicit |
| 230 | + # |
| 231 | +``` |
0 commit comments