docs/manual/customize-outside-br.txt

18    location a _br2-external tree_. This section explains how to use
19    the br2-external mechanism and what to provide in a br2-external
22 One can tell Buildroot to use one or more br2-external trees by setting
23 the +BR2_EXTERNAL+ make variable set to the path(s) of the br2-external
25 is automatically saved in the hidden +.br2-external.mk+ file in the output
31 The path to a br2-external tree can be either absolute or relative.
37 If using an br2-external tree from before Buildroot 2016.11, you need to
39 xref:br2-external-converting[] for help on doing so.
47 From now on, definitions from the +/path/to/foo+ br2-external tree
55 We can switch to another br2-external tree at any time:
61 We can also use multiple br2-external trees:
67 Or disable the usage of any br2-external tree:
73 ==== Layout of a br2-external tree
75 A br2-external tree must contain at least those three files, described
78  * +external.desc+
79  * +external.mk+
83 content that may be present in a br2-external tree, like the +configs/+
87 A complete example br2-external tree layout is also described later.
89 ===== The +external.desc+ file
91 That file describes the br2-external tree: the _name_ and _description_
92 for that br2-external tree.
99  * +name+, mandatory, defines the name for that br2-external tree. That
102    +BR2_EXTERNAL_$(NAME)_PATH+ to the absolute path of the br2-external
103    tree, so that you can use it to refer to your br2-external tree. This
107    data files) from your br2-external tree.
110 Since it is possible to use multiple br2-external trees at once, this
112   That name is used to identify your br2-external tree, so try to come up
113   with a name that really describes your br2-external tree, in order for
115   from another br2-external tree, especially if you are planning on
116   somehow sharing your br2-external tree with third parties or using
117   br2-external trees from third parties.
119  * +desc+, optional, provides a short description for that br2-external
121    and is used when displaying information about a br2-external tree (e.g.
141 ===== The +Config.in+ and +external.mk+ files
147 Buildroot automatically includes the +Config.in+ from each br2-external
149 the +external.mk+ from each br2-external tree with the rest of the
160 Then, have an +external.mk+ file that looks like:
173 custom make logic in +external.mk+.
178 the br2-external tree. Buildroot will automatically show them in the
181 'make list-defconfigs' output, below an +External configs+ label that
182 contains the name of the br2-external tree they are defined in.
185 If a defconfig file is present in more than one br2-external tree, then
186 the one from the last br2-external tree is used. It is thus possible
187 to override a defconfig bundled in Buildroot or another br2-external
198 It is possible for a br2-external to extend those choices, by providing
229 br2-external tree.
233 Here is an example layout using all features of br2-external (the sample
235 the br2-external tree; this is all entirely made up just for the sake of
240   |- external.desc
242   |     |desc: Example br2-external tree
246   |     |source "$BR2_EXTERNAL_BAR_42_PATH/toolchain/toolchain-external-mine/Config.in.options"
256   |- external.mk
341   |- toolchain/toolchain-external-mine/Config.in.options
346   |     |    default "toolchain-external-mine"
349   |- toolchain/toolchain-external-mine/toolchain-external-mine.mk
352   |     |$(eval $(toolchain-external-package))
357   |     |    bool "example-external-driver"
359   |     |      Example external driver
388 The br2-external tree will then be visible in the menuconfig (with
392 External options  --->
393     *** Example br2-external tree (in /path/to/br2-ext-tree/)
399 If you are using more than one br2-external tree, it would look like
401 +desc:+ field in +external.desc+):
404 External options  --->
405     Example br2-external tree  --->
406         *** Example br2-external tree (in /path/to/br2-ext-tree)
426                         *** jpeg from: Example br2-external tree ***
438             *** Toolchains from: Example br2-external tree ***
443 The toolchain options in +toolchain/toolchain-external-mine/Config.in.options+
445 from within the br2-external's top-level +Config.in+ and will thus appear
446 in the `External options` menu.