docs/0_Getting_Started/2_Developing_an_AGL_Image/4_Customizing_Your_Build.md

   1 ---
   2 edit_link: ''
   3 title: Customizing Your Build
   4 origin_url: >-
   5   https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/getting-started/image-workflow-cust-build.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 # 4. Customizing Your Build
  11
  12 Because the build process is based on BitBake and the Yocto Project,
  13 build customizations are driven through configuration files used during
  14 the build.
  15
  16 Lots of configuration files exist that define a build.
  17 However, the primary one that acts as a global configuration mechanism is the
  18 `local.conf` file, which is found in the Build Directory in a folder named "conf".
  19
  20 Before you start your build process, you should open up the `local.conf` file
  21 and look through it to be sure the general configurations are correct.
  22 The file is well commented so you should be able to understand what the
  23 various variables accomplish.
  24
  25 To view and customize the `local.conf` file, use any text editor:
  26
  27 ```bash
  28 $ vi $AGL_TOP/build/conf/local.conf
  29 ```
  30
  31 As mentioned in the "[Initializing Your Build Environment](./image-workflow-initialize-build-environment.html#initializing-your-build-environment.html)" section,
  32 the `local.conf` file gets augmented with AGL configuration fragments based on
  33 how you execute the `aglsetup.sh` script.
  34 You can see those fragments at the end the configuration file.
  35
  36 Even though your build should work fine after running the `aglsetup.sh` script,
  37 you might consider editing your `local.conf` file to use one or more of the
  38 following configurations.
  39
  40 ## Capturing Build History
  41
  42 You can enable build history to help maintain the quality of your build output.
  43 You can use it to highlight unexpected and possibly unwanted changes in the build output.
  44 Basically, with build history enabled, you get a record of information about the contents
  45 of each package and image.
  46 That information is committed to a local Git repository where you can examine it.
  47
  48 To enable build history, make sure the following two lines are in your
  49 `local.conf` file:
  50
  51 ```bash
  52 INHERIT += "buildhistory"
  53 BUILDHISTORY_COMMIT = "1"
  54 ```
  55
  56 See the
  57 "[Maintaining Build Output Quality](https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#maintaining-build-output-quality)"
  58 section in the Yocto Project Reference Manual for a complete discussion on
  59 build history.
  60
  61 ## Deleting Temporary Workspace
  62
  63 During a build, the build system uses a lot of disk space to store temporary files.
  64 You can ease the burden on your system and speed up the build by configuring the build
  65 to remove temporary workspace.
  66
  67 You need to inherit the `rm_work` class by using this statement in the `local.conf` file:
  68
  69 ```bash
  70 INHERIT += "rm_work"
  71 ```
  72
  73 You can read about the class in the
  74 "[rm_work.bbclass](https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#ref-classes-rm-work)"
  75 section of the Yocto Project Reference Manual for more information.
  76
  77 ##  Pointing at Shared State Cache Locations
  78
  79 The build system creates everything from scratch unless BitBake can determine that parts do not need to be rebuilt. Fundamentally, building from scratch is attractive as it means all parts are built fresh and there is no possibility of stale data causing problems.
  80 When developers hit problems, they typically default back to building from scratch so they know the state
  81 of things from the start.
  82
  83 The build process uses Shared State Cache (sstate) to speed up subsequent builds.
  84 This cache retains artifacts that can be re-used once it is determined that they
  85 would not be different as compared to a re-built module.
  86
  87 For the AGL build, you can specify the location for sstate files by including the
  88 following in the `local.conf` file:
  89
  90 ```bash
  91 SSTATE_DIR = "${HOME}/workspace_agl/sstate-cache"
  92 ```
  93
  94 also, in the `local.conf` file, you can specify additional directories in which the build
  95 system can look for shared state information.
  96 Use the following form in your file to list out the directories you want the build
  97 process to look at for sstate information:
  98
  99
 100 ```bash
 101 SSTATE_MIRRORS ?= "\
 102      file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
 103      file://.* file:///some/local/dir/sstate/PATH"
 104 ```
 105
 106 If you want to know more about the Yocto Project sstate mechanism, see the
 107 "[Shared State Cache](https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#shared-state-cache)"
 108 section in the Yocto Project Reference Manual.
 109
 110 ## Preserving the Download Directory
 111
 112 During the initial build, the system downloads many different source code tarballs
 113 from various upstream projects.
 114 Downloading these files can take a while, particularly if your network
 115 connection is slow.
 116 The process downloads files into a
 117 "[download directory](https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#var-DL_DIR)".
 118 The `DL_DIR` variable defines the download directory.
 119 For subsequent builds, you can preserve this directory to speed up the download
 120 part of a build.
 121
 122 The default download directory is in a folder named "downloads".
 123 For the AGL build you can set the download directory by adding the following to your
 124 `local.conf` file:
 125
 126 ```bash
 127 DL_DIR = "${HOME}/workspace_agl/downloads"
 128 ```
 129
 130 ## Using a Shared State (sstate) Mirror
 131
 132 The underlying Yocto Project build system uses Shared State Mirrors to cache
 133 artifacts from previous builds.
 134 You can significantly speed up builds and guard against fetcher failures by
 135 using mirrors.
 136 To use mirrors, add this line to your `local.conf` file in the Build directory:
 137
 138 ```
 139 SSTATE_MIRRORS_append = " file://.* https://download.automotivelinux.org/sstate-mirror/master/${DEFAULTTUNE}/PATH \n "
 140 ```
 141
 142 You can learn more about shared state and how it is used in the
 143 "[Shared State Cache](https://yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#shared-state-cache)"
 144 section of the Yocto Project Reference Manual.
 145