docs/01_Getting_Started/02_Building_AGL_Image/04_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        dragonboard-410c           # Qualcomm Dragonboard 410c
  40        dragonboard-820c           # Qualcomm Dragonboard 820c
  41        ebisu                      # Renesas RCar Ebisu
  42        h3-salvator-x              # Renesas RCar Salvator/H3
  43        h3ulcb                     # Renesas RCar H3
  44        h3ulcb-kf                  # Renesas RCar H3 w Kingfisher Board
  45        h3ulcb-nogfx               # Renesas RCar H3 w/o gfx blobs
  46        hsdk                       # ARC HS
  47        imx6qdlsabreauto           # i.MX6 sabreauto
  48        imx8mqevk                  # i.MX8 w etnaviv
  49        imx8mqevk-viv              # i.MX8 w vivante
  50        intel-corei7-64            # x86-64 (Intel flavour)
  51        j7-evm                     # TI Jacinto 7 EVM
  52        m3-salvator-x              # Renesas RCar Salvator/M3
  53        m3ulcb                     # Renesas RCar M3
  54        m3ulcb-kf                  # Renesas RCar M3 w Kingfisher Board
  55        m3ulcb-nogfx               # Renesas RCAR M3 w/o gfx blobs
  56        nitrogen6x                 # i.MX6 nitrogen board
  57        qemuarm                    # Qemu ARM
  58        qemuarm64                  # Qemu AArch 64 (ARM 64bit)
  59      * qemux86-64                 # Qemu x86-64
  60        raspberrypi4               # Raspberry Pi 4
  61        virtio-aarch64             # Virtio Guest
  62
  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
  77    [meta-agl]                                    # CORE layer
  78        Refer: https://git.automotivelinux.org/AGL/meta-agl/tree/templates/feature
  79        agl-all-features                          # For the usual demo image
  80        agl-app-framework                         # Application Framework
  81        agl-archiver                              # Source Archiver
  82        agl-buildstats                            # Build Statistics
  83        agl-ci-change-features-nogfx              # CI: features enabled for gerrit change builds w/o  gfx
  84        agl-ci-change-features                    # CI: features enabled for gerrit change builds with gfx
  85        agl-ci-snapshot-features-nogfx            # CI: features enabled for nightly builds w/o  gfx
  86        agl-ci-snapshot-features                  # CI: features enabled for nightly builds with gfx
  87        agl-ci                                    # CI: specific settings for the CI environment
  88        agl-create-spdx                           # Software Bill of Materials (SBOM) generation
  89        agl-devel :( agl-package-management )     # Developer Env (root login w/o pass)
  90        agl-fossdriver                            # Fossology integration, Scancode, etc.
  91        agl-localdev                              # inclusion of local development folder ./meta-localdev
  92        agl-netboot                               # network boot (e.g. in CI)
  93        agl-package-management                    # include package management (e.g. rpm)
  94        agl-pipewire                              # include pipewire
  95        agl-ptest                                 # enable ptest pckages
  96        agl-refhw-h3                              # enable reference hardware when building h3ulcb machine
  97        agl-selinux                               # Enables building with SELinux
  98        agl-virt                                  # EG-Virt features
  99        agl-virt-guest-xen                        # EG-Virt features
 100        agl-virt-xen                              # EG-Virt features
 101        agl-weston-remoting                       # remote streaming support
 102        agl-weston-waltham-remoting               # remote streaming support w/ waltham
 103
 104    [meta-agl-demo]                                    # DEMO layer
 105        Refer: https://git.automotivelinux.org/AGL/meta-agl-demo/tree/templates/feature
 106        agl-demo                                       # default IVI demo
 107        agl-kvm                                        # Enables support for building multiconfig based KVM+QEMU demo images
 108
 109    [meta-agl-devel]                                   # Development layer
 110        Refer: https://git.automotivelinux.org/AGL/meta-agl-devel/tree/templates/feature
 111        agl-basesystem                                 # Toyota basesystem
 112        agl-drm-lease                                  # DRM lease support
 113        agl-egvirt                                     # EG-Virt feature
 114        agl-flutter                                    # Flutter support
 115        agl-ic-container                               # Instrument Cluster EG demo using containers
 116        agl-offline-voice-agent                        # Feature template for meta-offline-voice-agent layer
 117        agl-test                                       # Test framework under development
 118
 119 ```
 120
 121 To find out exactly what a feature provides, check out the respective layer and its README.
 122
 123 An AGL feature is a configuration that accounts for specific settings
 124 and dependencies needed for a particular build.
 125 For example, specifying the "agl-demo" feature makes sure that the
 126 `aglsetup.sh` script creates configuration files needed to build the
 127 image for the AGL demo.
 128
 129 Following are brief descriptions of the AGL features you can specify on the
 130 `aglsetup.sh` command line:
 131
 132 * **agl-all-features**: A set of AGL default features.
 133   Do not think of this set of features as all the AGL features.
 134
 135 * **agl-app-framework**: Application Framework
 136
 137 * **agl-archiver**: Enables the archiver class for releases.
 138
 139 * **agl-ci**: Flags used for Continuous Integration (CI).
 140   Using this feature changes the value of the
 141   [`IMAGE_FSTYPES`](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-IMAGE_FSTYPES)
 142   variable.
 143
 144 * **agl-ci-change-features**: Enables features for CI builds for Gerrit changes.
 145
 146 * **agl-ci-change-features-nogfx**: Enables features for CI builds for Gerrit changes
 147   for targets that use binary graphics drivers (i.e. builds without graphics).
 148
 149 * **agl-ci-snapshot-features**: Enables features for CI daily snapshot builds.
 150
 151 * **agl-ci-snapshot-features-nogfx**: Enables features for CI daily snapshot builds for
 152   targets that use binary graphics drivers (i.e. builds without graphics).
 153
 154 * **agl-devel**: Activates development options such as an empty root password,
 155   debuggers, strace, valgrind, and so forth.
 156
 157 * **agl-netboot**: Enables network boot support through Trivial File Transfer Protocol (TFTP) and Network Block Device (NBD) protocol.
 158   Netboot is needed for CI and useful for development to avoid writing
 159   sdcards. Needs additional setup.
 160
 161 * **agl-ptest**: Enables
 162   [Ptest](https://docs.yoctoproject.org/dev-manual/common-tasks.html#testing-packages-with-ptest)
 163   as part of the build.
 164
 165 * **agl-demo**: Enables the layers meta-agl-demo and meta-qt5.
 166   You need agl-demo if you are going to build the agl-ivi-demo-qt.
 167
 168 * **agl-pipewire**: Enables AGLs pipewire support.
 169
 170 * **agl-localdev**: Adds a local layer named "meta-localdev" in the
 171   meta directory and a local.dev.inc configuration file when that file
 172   is present.
 173
 174   This feature provides a shortcut for using the layer meta-localdev
 175   in the top-level folder for easy modifications to your own recipes.
 176
 177 ## Example
 178
 179 Following is an example that initializes the build environment, selects "beaglebone"
 180 for the machine, and chooses the "agl-demo" feature, which also includes the
 181 "agl-appfw-smack", "agl-devel", and "agl-hmi-framework" features:
 182
 183 ```sh
 184 $ source meta-agl/scripts/aglsetup.sh -m qemux86-64 -b qemux86-64 agl-demo agl-devel
 185 aglsetup.sh: Starting
 186 Generating configuration files:
 187    Build dir: /home/scottrif/workspace_agl/build
 188    Machine: qemux86-64
 189    Features: agl-appfw-smack agl-demo agl-devel
 190    Running /home/scottrif/workspace_agl/poky/oe-init-build-env
 191    Templates dir: /home/scottrif/workspace_agl/meta-agl/templates/base
 192    Config: /home/scottrif/workspace_agl/build/conf/bblayers.conf
 193    Config: /home/scottrif/workspace_agl/build/conf/local.conf
 194    Setup script: /home/scottrif/workspace_agl/build/conf/setup.sh
 195    Executing setup script ... --- beginning of setup script
 196  fragment /home/scottrif/workspace_agl/meta-agl/templates/base/01_setup_EULAfunc.sh
 197  fragment /home/scottrif/workspace_agl/meta-agl/templates/base/99_setup_EULAconf.sh
 198  end of setup script
 199 OK
 200 Generating setup file: /home/scottrif/workspace_agl/build/agl-init-build-env ... OK
 201 aglsetup.sh: Done
 202  Shell environment set up for builds.
 203 You can now run 'bitbake target'
 204 Common targets are:
 205 - meta-agl layer:
 206   - included by default
 207     * agl-image-boot                (just enough to boot)
 208     * agl-image-minimal             (minimal filesystem with APIs)
 209     * agl-image-minimal-crosssdk    (crosssdk for ^^)
 210
 211     * agl-image-weston              (minimal filesystem with weston)
 212     * agl-image-compositor          (minimal filesystem with AGL compositor)
 213
 214 - meta-agl-demo:                    (IVI demo with UI)
 215   - with 'agl-demo'
 216     * agl-ivi-image                 (base for IVI targets)
 217     * agl-ivi-image-crosssdk        (sdk for ^^)
 218
 219     * agl-ivi-demo-qt               (IVI Qt demo image)
 220     * agl-ivi-demo-qt-crosssdk      (sdk for ^^)
 221     * agl-ivi-demo-flutter          (IVI Flutter demo image)
 222     * agl-ivi-demo-html5            (IVI HTML5 demo image)
 223
 224     * agl-cluster-demo-qt           (cluster Qt demo image)
 225     * agl-cluster-demo-flutter      (cluster Flutter demo image)
 226
 227     * agl-telematics-demo           (telematics demo image)
 228
 229     * agl-gateway-demo              (gateway demo image)
 230 ```
 231
 232 Running the script creates the Build Directory if it does not already exist.
 233 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>`
 234 For this example, the Build Directory is `$AGL_TOP/master/qemux86-64`.
 235
 236 The script's output also indicates the machine and AGL features selected for the build.
 237
 238 The script creates two primary configuration files used for the build: `local.conf` and `bblayers.conf`.
 239 Both these configuration files are located in the Build Directory in the `conf` folder.
 240 If you were to examine these files, you would find standard Yocto Project
 241 configurations along with AGL configuration fragments, which are driven by the
 242 machine (i.e. beaglebone) and the AGL features specified as part of the
 243 script's command line.
 244
 245 The end result is configuration files specific for your build in the AGL development environment.
 246
 247 Finally, part of the `aglsetup.sh` script makes sure that any End User License Agreements (EULA)
 248 are considered.
 249 You can see that processing in the script's output as well.
 250
 251 **NOTE:** Use of the `local.conf` and `bblayers.conf` configuration files is fundamental
 252 in the Yocto Project build environment.
 253 Consequently, it is fundamental in the AGL build environment.
 254 You can find lots of information on configuring builds in the Yocto Project
 255 documentation set.
 256 Here are some references if you want to dig into configuration further:
 257
 258 * [Customizing Images Using local.conf](https://docs.yoctoproject.org/dev-manual/common-tasks.html#customizing-images-using-local-conf)
 259 * [Local](https://docs.yoctoproject.org/ref-manual/varlocality.html#local)
 260 * [build/conf/local.conf](https://docs.yoctoproject.org/ref-manual/structure.html#build-conf-local-conf)
 261 * [build/conf/bblayers.conf](https://docs.yoctoproject.org/ref-manual/structure.html#build-conf-bblayers-conf)
 262 * [BBLAYERS](https://docs.yoctoproject.org/ref-manual/variables.html#term-BBLAYERS)
 263 * [User Configuration](https://docs.yoctoproject.org/ref-manual/structure.html#build)
 264 * [Enabling Your Layer](https://docs.yoctoproject.org/dev-manual/common-tasks.html#enabling-your-layer)