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/master/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/master
  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                        # BeagleBoneEnhanced
  37        beaglebone                 # BeagleBone
  38        cubox-i                    # multiple i.MX6 boards
  39        cyclone5                   # CycloneV
  40        dra7xx-evm                 # TI DRA7xx-EVM 'vayu'
  41        dragonboard-410c           # Qualcomm Dragonboard 410c
  42        dragonboard-820c           # Qualcomm Dragonboard 820c
  43        ebisu                      # Renesas RCar Ebisu
  44        h3-salvator-x              # Renesas RCar Salvator/H3
  45        h3ulcb                     # Renesas RCar H3
  46        h3ulcb-kf                  # Renesas RCar H3 w Kingfisher Board
  47        h3ulcb-nogfx               # Renesas RCar H3 w/o gfx blobs
  48        hsdk                       # ARC HS
  49        imx6qdlsabreauto           # i.MX6 sabreauto
  50        imx8mqevk                  # i.MX8 w etnaviv
  51        imx8mqevk-viv              # i.MX8 w vivante
  52        intel-corei7-64            # x86-64 (Intel flavour)
  53        m3-salvator-x              # Renesas RCar Salvator/M3
  54        m3ulcb                     # Renesas RCar M3
  55        m3ulcb-kf                  # Renesas RCar M3 w Kingfisher Board
  56        m3ulcb-nogfx               # Renesas RCAR M3 w/o gfx blobs
  57        nitrogen6x                 # i.MX6 nitrogen board
  58        qemuarm                    # Qemu ARM
  59        qemuarm64                  # Qemu AArch 64 (ARM 64bit)
  60      * qemux86-64                 # Qemu x86-64
  61        raspberrypi4               # Raspberry Pi 4
  62 ```
  63
  64 ## AGL Features
  65
  66 Before running the `aglsetup.sh`, you should understand what AGL features you
  67 want to include as part of your image.
  68 The script's help output lists available features and shows you the layers in
  69 which they reside.
  70
  71 Following is a list of the available features:
  72
  73 ```sh
  74 Available features:
  75    [meta-agl]
  76        agl-all-features :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-profile-graphical-qt5  agl-profile-graphical  agl-pipewire  agl-speech-framework  agl-netboot )
  77        agl-appfw-smack
  78        agl-archiver
  79        agl-buildstats
  80        agl-ci
  81        agl-ci-change-features :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-profile-graphical-qt5  agl-profile-graphical  agl-pipewire  agl-speech-framework  agl-devel  agl-netboot  agl-pipewire  agl-cloudproxy  agl-buildstats  agl-ptest )
  82        agl-ci-change-features-nogfx :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-profile-graphical-qt5  agl-profile-graphical  agl-pipewire  agl-speech-framework  agl-devel  agl-netboot  agl-pipewire  agl-cloudproxy  agl-buildstats  agl-ptest )
  83        agl-ci-snapshot-features :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-profile-graphical-qt5  agl-profile-graphical  agl-pipewire  agl-speech-framework  agl-devel  agl-netboot  agl-archiver  agl-pipewire  agl-buildstats  agl-ptest )
  84        agl-ci-snapshot-features-nogfx :( agl-demo  agl-appfw-smack  agl-hmi-framework  agl-profile-graphical-qt5  agl-profile-graphical  agl-pipewire  agl-speech-framework  agl-devel  agl-netboot  agl-archiver  agl-pipewire  agl-buildstats  agl-ptest )
  85        agl-devel
  86        agl-fossdriver
  87        agl-gplv2
  88        agl-hmi-framework
  89        agl-netboot
  90        agl-pipewire
  91        agl-profile-cluster :( agl-profile-graphical )
  92        agl-profile-cluster-qt5 :( agl-profile-graphical-qt5  agl-profile-graphical )
  93        agl-profile-graphical
  94        agl-profile-graphical-html5 :( agl-profile-graphical )
  95        agl-profile-graphical-qt5 :( agl-profile-graphical )
  96        agl-profile-hud
  97        agl-profile-telematics
  98        agl-ptest
  99        agl-sign-wgts
 100        agl-sota
 101        agl-virt
 102        agl-virt-guest-xen
 103        agl-virt-xen :( agl-virt )
 104        agl-weston-remoting :( agl-profile-graphical )
 105    [meta-agl-cluster-demo]
 106        agl-cluster-demo :( agl-profile-cluster-qt5  agl-profile-graphical-qt5  agl-profile-graphical  agl-hmi-framework )
 107        agl-cluster-demo-preload
 108    [meta-agl-demo]
 109        agl-cloudproxy
 110        agl-cluster-demo-support :( agl-weston-remoting  agl-profile-graphical )
 111        agl-demo :( agl-appfw-smack  agl-hmi-framework  agl-profile-graphical-qt5  agl-profile-graphical  agl-pipewire  agl-speech-framework )
 112        agl-demo-preload
 113        agl-demo-soundmanager :( agl-appfw-smack  agl-hmi-framework  agl-profile-graphical-qt5  agl-profile-graphical  agl-audio-soundmanager-framework )
 114    [meta-agl-devel]
 115        agl-jailhouse
 116        agl-speech-framework
 117        agl-voiceagent-alexa :( agl-speech-framework )
 118        agl-voiceagent-alexa-wakeword :( agl-voiceagent-alexa  agl-speech-framework )
 119    [meta-agl-extra]
 120        agl-localdev
 121    [meta-agl-telematics-demo]
 122        agl-telematics-demo :( agl-profile-telematics )
 123 ```
 124
 125 To find out exactly what a feature provides, check out the respective layer and its README.
 126
 127 An AGL feature is a configuration that accounts for specific settings
 128 and dependencies needed for a particular build.
 129 For example, specifying the "agl-demo" feature makes sure that the
 130 `aglsetup.sh` script creates configuration files needed to build the
 131 image for the AGL demo.
 132
 133 Following are brief descriptions of the AGL features you can specify on the
 134 `aglsetup.sh` command line:
 135
 136 * **agl-all-features**: A set of AGL default features.
 137   Do not think of this set of features as all the AGL features.
 138
 139 * **agl-appfw-smack**: Enables IoT.bzh Application Framework plus SMACK and
 140   Cynara.
 141
 142 * **agl-archiver**: Enables the archiver class for releases.
 143
 144 * **agl-ci**: Flags used for Continuous Integration (CI).
 145   Using this feature changes the value of the
 146   [`IMAGE_FSTYPES`](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-IMAGE_FSTYPES)
 147   variable.
 148
 149 * **agl-ci-change-features**: Enables features for CI builds for Gerrit changes.
 150
 151 * **agl-ci-change-features-nogfx**: Enables features for CI builds for Gerrit changes
 152   for targets that use binary graphics drivers (i.e. builds without graphics).
 153
 154 * **agl-ci-snapshot-features**: Enables features for CI daily snapshot builds.
 155
 156 * **agl-ci-snapshot-features-nogfx**: Enables features for CI daily snapshot builds for
 157   targets that use binary graphics drivers (i.e. builds without graphics).
 158
 159 * **agl-devel**: Activates development options such as an empty root password,
 160   debuggers, strace, valgrind, and so forth.
 161
 162 * **agl-netboot**: Enables network boot support through Trivial File Transfer Protocol (TFTP) and Network Block Device (NBD) protocol.
 163   Netboot is needed for CI and useful for development to avoid writing
 164   sdcards. Needs additional setup.
 165
 166 <!--
 167 * **agl-profile**: A group or set of Layers and a Package Group as used
 168   by the Yocto Project.
 169   This feature helps define dependency for various profiles and layers
 170   used during the build.
 171   For example, "agl-demo" depends on "agl-profile-graphical-qt", which
 172   in turn depends on "agl-profile-graphical", which in turn depends
 173   on "agl-profile-core".
 174
 175   agl-profile-graphical
 176   agl-profile-graphical-html5
 177   agl-profile-graphical-qt5
 178   agl-profile-hud
 179   agl-profile-telematics
 180
 181   **NOTE:** For information on Package Groups, see the
 182   "[Customizing Images Using Custom Package Groups](https://www.yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks)"
 183   section in the Yocto Project Development Tasks Manual.
 184   You can also find general information about Layers in the
 185   "[Layers](https://www.yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#yocto-project-layers)"
 186   section in that same manual.
 187 -->
 188
 189 * **agl-ptest**: Enables
 190   [Ptest](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#testing-packages-with-ptest)
 191   as part of the build.
 192
 193 * **agl-sota**: Enables Software Over-the-Air (SOTA) components and dependencies.
 194   Includes meta-updater, meta-updater-qemux86-64, meta-filesystems, and meta-python.
 195
 196 * **agl-demo**: Enables the layers meta-agl-demo and meta-qt5.
 197   You need agl-demo if you are going to build the agl-demo-platform.
 198
 199 * **agl-sdl**: Enables or adds SDL to the build.
 200
 201 * **agl-pipewire**: Enables AGLs pipewire support.
 202
 203 * **agl-audio-soundmanager-framework**: Enables Soundmanager framework, which is an exclusive switch for audio framework.
 204
 205 * **agl-localdev**: Adds a local layer named "meta-localdev" in the
 206   meta directory and a local.dev.inc configuration file when that file
 207   is present.
 208
 209   This feature provides a shortcut for using the layer meta-localdev
 210   in the top-level folder for easy modifications to your own recipes.
 211
 212 ## Example
 213
 214 Following is an example that initializes the build environment, selects "beaglebone"
 215 for the machine, and chooses the "agl-demo" feature, which also includes the
 216 "agl-appfw-smack", "agl-devel", and "agl-hmi-framework" features:
 217
 218 ```sh
 219 $ source meta-agl/scripts/aglsetup.sh -m qemux86-64 -b qemux86-64 agl-demo agl-devel
 220 aglsetup.sh: Starting
 221 Generating configuration files:
 222    Build dir: /home/scottrif/workspace_agl/build
 223    Machine: qemux86-64
 224    Features: agl-appfw-smack agl-demo agl-devel
 225    Running /home/scottrif/workspace_agl/poky/oe-init-build-env
 226    Templates dir: /home/scottrif/workspace_agl/meta-agl/templates/base
 227    Config: /home/scottrif/workspace_agl/build/conf/bblayers.conf
 228    Config: /home/scottrif/workspace_agl/build/conf/local.conf
 229    Setup script: /home/scottrif/workspace_agl/build/conf/setup.sh
 230    Executing setup script ... --- beginning of setup script
 231  fragment /home/scottrif/workspace_agl/meta-agl/templates/base/01_setup_EULAfunc.sh
 232  fragment /home/scottrif/workspace_agl/meta-agl/templates/base/99_setup_EULAconf.sh
 233  end of setup script
 234 OK
 235 Generating setup file: /home/scottrif/workspace_agl/build/agl-init-build-env ... OK
 236 aglsetup.sh: Done
 237  Shell environment set up for builds.
 238 You can now run 'bitbake target'
 239 Common targets are:
 240   - meta-agl:          (core system)
 241     agl-image-minimal
 242     agl-image-minimal-qa
 243
 244     agl-image-ivi
 245     agl-image-ivi-qa
 246     agl-image-ivi-crosssdk
 247
 248     agl-image-weston
 249
 250   - meta-agl-demo:     (demo with UI)
 251     agl-demo-platform  (* default demo target)
 252     agl-demo-platform-qa
 253     agl-demo-platform-crosssdk
 254     agl-demo-platform-html5
 255 ```
 256
 257 Running the script creates the Build Directory if it does not already exist.
 258 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>`
 259 For this example, the Build Directory is `$AGL_TOP/master/qemux86-64`.
 260
 261 The script's output also indicates the machine and AGL features selected for the build.
 262
 263 The script creates two primary configuration files used for the build: `local.conf` and `bblayers.conf`.
 264 Both these configuration files are located in the Build Directory in the `conf` folder.
 265 If you were to examine these files, you would find standard Yocto Project
 266 configurations along with AGL configuration fragments, which are driven by the
 267 machine (i.e. beaglebone) and the AGL features specified as part of the
 268 script's command line.
 269
 270 The end result is configuration files specific for your build in the AGL development environment.
 271
 272 Finally, part of the `aglsetup.sh` script makes sure that any End User License Agreements (EULA)
 273 are considered.
 274 You can see that processing in the script's output as well.
 275
 276 **NOTE:** Use of the `local.conf` and `bblayers.conf` configuration files is fundamental
 277 in the Yocto Project build environment.
 278 Consequently, it is fundamental in the AGL build environment.
 279 You can find lots of information on configuring builds in the Yocto Project
 280 documentation set.
 281 Here are some references if you want to dig into configuration further:
 282
 283 * [Customizing Images Using local.conf](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-localconf)
 284 * [Local](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#ref-varlocality-config-local)
 285 * [build/conf/local.conf](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#structure-build-conf-local.conf)
 286 * [build/conf/bblayers.conf](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf)
 287 * [BBLAYERS](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-BBLAYERS)
 288 * [User Configuration](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#user-configuration)
 289 * [Enabling Your Layer](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#enabling-your-layer)