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-cluster-support                       # Add streaming to cluster of AGL demo system
 107        agl-demo-preload                               # Add Tokens and sample files specific to AGL demo system
 108        agl-demo                                       # default IVI demo
 109        agl-kvm                                        # Enables support for building multiconfig based KVM+QEMU demo images
 110
 111    [meta-agl-devel]                                   # Development layer
 112        Refer: https://git.automotivelinux.org/AGL/meta-agl-devel/tree/templates/feature
 113        agl-basesystem                                 # Toyota basesystem
 114        agl-drm-lease                                  # DRM lease support
 115        agl-egvirt                                     # EG-Virt feature
 116        agl-flutter                                    # Flutter support
 117        agl-ic-container                               # Instrument Cluster EG demo using containers
 118        agl-jailhouse                                  # GSoC: jailhouse enablement
 119        agl-offline-voice-agent                        # Feature template for meta-offline-voice-agent layer
 120        agl-test                                       # Test frameword under development
 121
 122 ```
 123
 124 To find out exactly what a feature provides, check out the respective layer and its README.
 125
 126 An AGL feature is a configuration that accounts for specific settings
 127 and dependencies needed for a particular build.
 128 For example, specifying the "agl-demo" feature makes sure that the
 129 `aglsetup.sh` script creates configuration files needed to build the
 130 image for the AGL demo.
 131
 132 Following are brief descriptions of the AGL features you can specify on the
 133 `aglsetup.sh` command line:
 134
 135 * **agl-all-features**: A set of AGL default features.
 136   Do not think of this set of features as all the AGL features.
 137
 138 * **agl-app-framework**: Application Framework
 139
 140 * **agl-archiver**: Enables the archiver class for releases.
 141
 142 * **agl-ci**: Flags used for Continuous Integration (CI).
 143   Using this feature changes the value of the
 144   [`IMAGE_FSTYPES`](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-IMAGE_FSTYPES)
 145   variable.
 146
 147 * **agl-ci-change-features**: Enables features for CI builds for Gerrit changes.
 148
 149 * **agl-ci-change-features-nogfx**: Enables features for CI builds for Gerrit changes
 150   for targets that use binary graphics drivers (i.e. builds without graphics).
 151
 152 * **agl-ci-snapshot-features**: Enables features for CI daily snapshot builds.
 153
 154 * **agl-ci-snapshot-features-nogfx**: Enables features for CI daily snapshot builds for
 155   targets that use binary graphics drivers (i.e. builds without graphics).
 156
 157 * **agl-devel**: Activates development options such as an empty root password,
 158   debuggers, strace, valgrind, and so forth.
 159
 160 * **agl-netboot**: Enables network boot support through Trivial File Transfer Protocol (TFTP) and Network Block Device (NBD) protocol.
 161   Netboot is needed for CI and useful for development to avoid writing
 162   sdcards. Needs additional setup.
 163
 164 * **agl-ptest**: Enables
 165   [Ptest](https://docs.yoctoproject.org/dev-manual/common-tasks.html#testing-packages-with-ptest)
 166   as part of the build.
 167
 168 * **agl-demo**: Enables the layers meta-agl-demo and meta-qt5.
 169   You need agl-demo if you are going to build the agl-demo-platform.
 170
 171 * **agl-pipewire**: Enables AGLs pipewire support.
 172
 173 * **agl-localdev**: Adds a local layer named "meta-localdev" in the
 174   meta directory and a local.dev.inc configuration file when that file
 175   is present.
 176
 177   This feature provides a shortcut for using the layer meta-localdev
 178   in the top-level folder for easy modifications to your own recipes.
 179
 180 ## Example
 181
 182 Following is an example that initializes the build environment, selects "beaglebone"
 183 for the machine, and chooses the "agl-demo" feature, which also includes the
 184 "agl-appfw-smack", "agl-devel", and "agl-hmi-framework" features:
 185
 186 ```sh
 187 $ source meta-agl/scripts/aglsetup.sh -m qemux86-64 -b qemux86-64 agl-demo agl-devel
 188 aglsetup.sh: Starting
 189 Generating configuration files:
 190    Build dir: /home/scottrif/workspace_agl/build
 191    Machine: qemux86-64
 192    Features: agl-appfw-smack agl-demo agl-devel
 193    Running /home/scottrif/workspace_agl/poky/oe-init-build-env
 194    Templates dir: /home/scottrif/workspace_agl/meta-agl/templates/base
 195    Config: /home/scottrif/workspace_agl/build/conf/bblayers.conf
 196    Config: /home/scottrif/workspace_agl/build/conf/local.conf
 197    Setup script: /home/scottrif/workspace_agl/build/conf/setup.sh
 198    Executing setup script ... --- beginning of setup script
 199  fragment /home/scottrif/workspace_agl/meta-agl/templates/base/01_setup_EULAfunc.sh
 200  fragment /home/scottrif/workspace_agl/meta-agl/templates/base/99_setup_EULAconf.sh
 201  end of setup script
 202 OK
 203 Generating setup file: /home/scottrif/workspace_agl/build/agl-init-build-env ... OK
 204 aglsetup.sh: Done
 205  Shell environment set up for builds.
 206 You can now run 'bitbake target'
 207 Common targets are:
 208   - meta-agl:          (core system)
 209     agl-image-minimal
 210     agl-image-minimal-qa
 211
 212     agl-image-ivi
 213     agl-image-ivi-qa
 214     agl-image-ivi-crosssdk
 215
 216     agl-image-weston
 217
 218   - meta-agl-demo:     (demo with UI)
 219     agl-demo-platform  (* default demo target)
 220     agl-demo-platform-qa
 221     agl-demo-platform-crosssdk
 222     agl-demo-platform-html5
 223 ```
 224
 225 Running the script creates the Build Directory if it does not already exist.
 226 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>`
 227 For this example, the Build Directory is `$AGL_TOP/master/qemux86-64`.
 228
 229 The script's output also indicates the machine and AGL features selected for the build.
 230
 231 The script creates two primary configuration files used for the build: `local.conf` and `bblayers.conf`.
 232 Both these configuration files are located in the Build Directory in the `conf` folder.
 233 If you were to examine these files, you would find standard Yocto Project
 234 configurations along with AGL configuration fragments, which are driven by the
 235 machine (i.e. beaglebone) and the AGL features specified as part of the
 236 script's command line.
 237
 238 The end result is configuration files specific for your build in the AGL development environment.
 239
 240 Finally, part of the `aglsetup.sh` script makes sure that any End User License Agreements (EULA)
 241 are considered.
 242 You can see that processing in the script's output as well.
 243
 244 **NOTE:** Use of the `local.conf` and `bblayers.conf` configuration files is fundamental
 245 in the Yocto Project build environment.
 246 Consequently, it is fundamental in the AGL build environment.
 247 You can find lots of information on configuring builds in the Yocto Project
 248 documentation set.
 249 Here are some references if you want to dig into configuration further:
 250
 251 * [Customizing Images Using local.conf](https://docs.yoctoproject.org/dev-manual/common-tasks.html#customizing-images-using-local-conf)
 252 * [Local](https://docs.yoctoproject.org/ref-manual/varlocality.html#local)
 253 * [build/conf/local.conf](https://docs.yoctoproject.org/ref-manual/structure.html#build-conf-local-conf)
 254 * [build/conf/bblayers.conf](https://docs.yoctoproject.org/ref-manual/structure.html#build-conf-bblayers-conf)
 255 * [BBLAYERS](https://docs.yoctoproject.org/ref-manual/variables.html#term-BBLAYERS)
 256 * [User Configuration](https://docs.yoctoproject.org/ref-manual/structure.html#build)
 257 * [Enabling Your Layer](https://docs.yoctoproject.org/dev-manual/common-tasks.html#enabling-your-layer)