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

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