docs/0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md

   1 ---
   2 title: Initializing Your Build Environment
   3 ---
   4
   5 Part of the downloaded AGL software is a setup script that you must
   6 run to initialize the build environment.
   7
   8 ## `aglsetup.sh` Script
   9
  10 You can find this script here:
  11
  12 ```sh
  13 $AGL_TOP/lamprey/meta-agl/scripts/aglsetup.sh
  14 ```
  15
  16 The script accepts many options that allow you to define build parameters such
  17 as the target hardware (i.e. the machine), build directory, and so forth.
  18 Use the following commands to see the available options and script syntax:
  19
  20 ```sh
  21 $ cd $AGL_TOP/lamprey
  22 $ source meta-agl/scripts/aglsetup.sh -h
  23 ```
  24
  25 ## AGL Machines (board support)
  26
  27 Your target platform will be selected with the `-m` flag.
  28 The MACHINE can be selected from the templates in `meta-agl/templates/machine/*`.
  29 Note: This is also the place where you can add new boards.
  30
  31 Following is a list of the available machines (level of support varies!):
  32
  33 ```sh
  34 Available machines:
  35    [meta-agl]
  36        bbe
  37        beaglebone
  38        cubox-i
  39        dragonboard-410c
  40        dragonboard-820c
  41        ebisu
  42        h3-salvator-x
  43        h3ulcb
  44        h3ulcb-kf
  45        h3ulcb-nogfx
  46        hsdk
  47        imx6qdlsabreauto
  48        imx8mqevk
  49        imx8mqevk-viv
  50        intel-corei7-64
  51        j7-evm
  52        m3-salvator-x
  53        m3ulcb
  54        m3ulcb-kf
  55        m3ulcb-nogfx
  56        nitrogen6x
  57        qemuarm
  58        qemuarm64
  59        qemuriscv64
  60      * qemux86-64
  61        raspberrypi4
  62        virtio-aarch64
  63 ```
  64
  65 ## AGL Features
  66
  67 Before running the `aglsetup.sh`, you should understand what AGL features you
  68 want to include as part of your image.
  69 The script's help output lists available features and shows you the layers in
  70 which they reside.
  71
  72 Following is a list of the available features:
  73
  74 ```sh
  75 Available features:
  76    [meta-agl]
  77        agl-all-features :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-pipewire  agl-netboot )
  78        agl-appfw-smack
  79        agl-archiver
  80        agl-buildstats
  81        agl-ci
  82        agl-ci-change-features :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-pipewire  agl-devel  agl-package-management  agl-netboot  agl-pipewire  agl-cloudproxy  agl-buildstats  agl-ptest )
  83        agl-ci-change-features-nogfx :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-pipewire  agl-devel  agl-package-management  agl-netboot  agl-pipewire  agl-cloudproxy  agl-buildstats  agl-ptest )
  84        agl-ci-snapshot-features :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-pipewire  agl-devel  agl-package-management  agl-netboot  agl-archiver  agl-pipewire  agl-buildstats  agl-ptest )
  85        agl-ci-snapshot-features-nogfx :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-pipewire  agl-devel  agl-package-management  agl-netboot  agl-archiver  agl-pipewire  agl-buildstats  agl-ptest )
  86        agl-devel :( agl-package-management )
  87        agl-fossdriver
  88        agl-gplv2
  89        agl-hmi-framework
  90        agl-localdev
  91        agl-netboot
  92        agl-package-management
  93        agl-pipewire
  94        agl-ptest
  95        agl-refhw-h3
  96        agl-sign-wgts
  97        agl-sota
  98        agl-virt
  99        agl-virt-guest-xen
 100        agl-virt-xen :( agl-virt )
 101        agl-weston-remoting :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-pipewire )
 102        agl-weston-waltham-remoting :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-pipewire )
 103    [meta-agl-demo]
 104        agl-cloudproxy
 105        agl-cluster-demo-support :( agl-weston-remoting  agl-demo  agl-appfw-smack  agl-hmi-framework  agl-pipewire )
 106        agl-demo :( agl-appfw-smack  agl-hmi-framework  agl-pipewire )
 107        agl-demo-preload
 108    [meta-agl-devel]
 109        agl-basesystem
 110        agl-drm-lease
 111        agl-jailhouse
 112        agl-lxc :( agl-virt  agl-drm-lease )
 113        agl-voiceagent-alexa
 114        agl-voiceagent-alexa-wakeword :( agl-voiceagent-alexa )
 115 ```
 116
 117 To find out exactly what a feature provides, check out the respective layer and its README.
 118
 119 An AGL feature is a configuration that accounts for specific settings
 120 and dependencies needed for a particular build.
 121 For example, specifying the "agl-demo" feature makes sure that the
 122 `aglsetup.sh` script creates configuration files needed to build the
 123 image for the AGL demo.
 124
 125 Following are brief descriptions of the AGL features you can specify on the
 126 `aglsetup.sh` command line:
 127
 128 * **agl-all-features**: A set of AGL default features.
 129   Do not think of this set of features as all the AGL features.
 130
 131 * **agl-appfw-smack**: Enables IoT.bzh Application Framework plus SMACK and
 132   Cynara.
 133
 134 * **agl-archiver**: Enables the archiver class for releases.
 135
 136 * **agl-ci**: Flags used for Continuous Integration (CI).
 137   Using this feature changes the value of the
 138   [`IMAGE_FSTYPES`](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-IMAGE_FSTYPES)
 139   variable.
 140
 141 * **agl-ci-change-features**: Enables features for CI builds for Gerrit changes.
 142
 143 * **agl-ci-change-features-nogfx**: Enables features for CI builds for Gerrit changes
 144   for targets that use binary graphics drivers (i.e. builds without graphics).
 145
 146 * **agl-ci-snapshot-features**: Enables features for CI daily snapshot builds.
 147
 148 * **agl-ci-snapshot-features-nogfx**: Enables features for CI daily snapshot builds for
 149   targets that use binary graphics drivers (i.e. builds without graphics).
 150
 151 * **agl-devel**: Activates development options such as an empty root password,
 152   debuggers, strace, valgrind, and so forth.
 153
 154 * **agl-netboot**: Enables network boot support through Trivial File Transfer Protocol (TFTP) and Network Block Device (NBD) protocol.
 155   Netboot is needed for CI and useful for development to avoid writing
 156   sdcards. Needs additional setup.
 157
 158 <!--
 159 * **agl-profile**: A group or set of Layers and a Package Group as used
 160   by the Yocto Project.
 161   This feature helps define dependency for various profiles and layers
 162   used during the build.
 163   For example, "agl-demo" depends on "agl-profile-graphical-qt", which
 164   in turn depends on "agl-profile-graphical", which in turn depends
 165   on "agl-profile-core".
 166
 167   agl-profile-graphical
 168   agl-profile-graphical-html5
 169   agl-profile-graphical-qt5
 170   agl-profile-hud
 171   agl-profile-telematics
 172
 173   **NOTE:** For information on Package Groups, see the
 174   "[Customizing Images Using Custom Package Groups](https://www.yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks)"
 175   section in the Yocto Project Development Tasks Manual.
 176   You can also find general information about Layers in the
 177   "[Layers](https://www.yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#yocto-project-layers)"
 178   section in that same manual.
 179 -->
 180
 181 * **agl-ptest**: Enables
 182   [Ptest](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#testing-packages-with-ptest)
 183   as part of the build.
 184
 185 * **agl-demo**: Enables the layers meta-agl-demo and meta-qt5.
 186   You need agl-demo if you are going to build the agl-demo-platform.
 187
 188 * **agl-pipewire**: Enables AGLs pipewire support.
 189
 190 * **agl-localdev**: Adds a local layer named "meta-localdev" in the
 191   meta directory and a local.dev.inc configuration file when that file
 192   is present.
 193
 194   This feature provides a shortcut for using the layer meta-localdev
 195   in the top-level folder for easy modifications to your own recipes.
 196
 197 ## Example
 198
 199 Following is an example that initializes the build environment, selects "beaglebone"
 200 for the machine, and chooses the "agl-demo" feature, which also includes the
 201 "agl-appfw-smack", "agl-devel", and "agl-hmi-framework" features:
 202
 203 ```sh
 204 $ source meta-agl/scripts/aglsetup.sh -m qemux86-64 -b qemux86-64 agl-demo agl-devel
 205 aglsetup.sh: Starting
 206 Generating configuration files:
 207    Build dir: /home/scottrif/workspace_agl/build
 208    Machine: qemux86-64
 209    Features: agl-appfw-smack agl-demo agl-devel
 210    Running /home/scottrif/workspace_agl/poky/oe-init-build-env
 211    Templates dir: /home/scottrif/workspace_agl/meta-agl/templates/base
 212    Config: /home/scottrif/workspace_agl/build/conf/bblayers.conf
 213    Config: /home/scottrif/workspace_agl/build/conf/local.conf
 214    Setup script: /home/scottrif/workspace_agl/build/conf/setup.sh
 215    Executing setup script ... --- beginning of setup script
 216  fragment /home/scottrif/workspace_agl/meta-agl/templates/base/01_setup_EULAfunc.sh
 217  fragment /home/scottrif/workspace_agl/meta-agl/templates/base/99_setup_EULAconf.sh
 218  end of setup script
 219 OK
 220 Generating setup file: /home/scottrif/workspace_agl/build/agl-init-build-env ... OK
 221 aglsetup.sh: Done
 222  Shell environment set up for builds.
 223 You can now run 'bitbake target'
 224 Common targets are:
 225   - meta-agl:          (core system)
 226     agl-image-minimal
 227     agl-image-minimal-qa
 228
 229     agl-image-ivi
 230     agl-image-ivi-qa
 231     agl-image-ivi-crosssdk
 232
 233     agl-image-weston
 234
 235   - meta-agl-demo:     (demo with UI)
 236     agl-demo-platform  (* default demo target)
 237     agl-demo-platform-qa
 238     agl-demo-platform-crosssdk
 239     agl-demo-platform-html5
 240 ```
 241
 242 Running the script creates the Build Directory if it does not already exist.
 243 The default Build Directory is `$AGL_TOP/<release-branch-name>/build`, and the nomenclature to be used throughout this doc is going to be `$AGL_TOP/<release-branch-name>/<build-dir>`
 244 For this example, the Build Directory is `$AGL_TOP/lamprey/qemux86-64`.
 245
 246 The script's output also indicates the machine and AGL features selected for the build.
 247
 248 The script creates two primary configuration files used for the build: `local.conf` and `bblayers.conf`.
 249 Both these configuration files are located in the Build Directory in the `conf` folder.
 250 If you were to examine these files, you would find standard Yocto Project
 251 configurations along with AGL configuration fragments, which are driven by the
 252 machine (i.e. beaglebone) and the AGL features specified as part of the
 253 script's command line.
 254
 255 The end result is configuration files specific for your build in the AGL development environment.
 256
 257 Finally, part of the `aglsetup.sh` script makes sure that any End User License Agreements (EULA)
 258 are considered.
 259 You can see that processing in the script's output as well.
 260
 261 **NOTE:** Use of the `local.conf` and `bblayers.conf` configuration files is fundamental
 262 in the Yocto Project build environment.
 263 Consequently, it is fundamental in the AGL build environment.
 264 You can find lots of information on configuring builds in the Yocto Project
 265 documentation set.
 266 Here are some references if you want to dig into configuration further:
 267
 268 * [Customizing Images Using local.conf](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-localconf)
 269 * [Local](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#ref-varlocality-config-local)
 270 * [build/conf/local.conf](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#structure-build-conf-local.conf)
 271 * [build/conf/bblayers.conf](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf)
 272 * [BBLAYERS](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-BBLAYERS)
 273 * [User Configuration](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#user-configuration)
 274 * [Enabling Your Layer](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#enabling-your-layer)