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