diff options
| -rw-r--r-- | docs/getting-started/app-workflow-intro.md | 2 | ||||
| -rw-r--r-- | docs/getting-started/customize_bitbake_conf.md | 53 | ||||
| -rw-r--r-- | docs/getting-started/image-workflow-build.md | 17 | ||||
| -rw-r--r-- | docs/getting-started/image-workflow-cust-build.md | 119 | ||||
| -rw-r--r-- | docs/getting-started/image-workflow-download-sw.md | 108 | ||||
| -rw-r--r-- | docs/getting-started/image-workflow-initialize-build-environment.md | 255 | ||||
| -rw-r--r-- | docs/getting-started/image-workflow-intro.md | 31 | ||||
| -rw-r--r-- | docs/getting-started/image-workflow-prep-host.md | 76 | ||||
| -rw-r--r-- | docs/getting-started/images/image-developer-workflow.png | bin | 0 -> 48502 bytes | |||
| -rw-r--r-- | docs/getting-started/machines/intel.md | 231 | ||||
| -rw-r--r-- | docs/getting-started/source-code.md | 201 |
11 files changed, 706 insertions, 387 deletions
diff --git a/docs/getting-started/app-workflow-intro.md b/docs/getting-started/app-workflow-intro.md index 073496c..256e91f 100644 --- a/docs/getting-started/app-workflow-intro.md +++ b/docs/getting-started/app-workflow-intro.md @@ -14,7 +14,7 @@ in the AGL Documentation set. Links are provided when a set of steps is required that is documented elsewhere. - +<center><img src="images/app-developer-workflow.png"></center> 1. Download or build the image you are going to run on the hardware device. diff --git a/docs/getting-started/customize_bitbake_conf.md b/docs/getting-started/customize_bitbake_conf.md deleted file mode 100644 index fa466ca..0000000 --- a/docs/getting-started/customize_bitbake_conf.md +++ /dev/null @@ -1,53 +0,0 @@ -# Customize AGL build - -To customize the AGL build, you edit local.conf file, located in the build/conf directory. - -```bash -edit $AGL_TOP/build/conf/local.conf -``` - -## Buildhistory - -The OpenEmbedded build system creates this directory when you enable the build history feature. - -```bash -INHERIT += "buildhistory" -BUILDHISTORY_COMMIT = "1" -``` - -For more information please check [Here][buildhistory] - -## Deletion of temporary workspace - -Removes work files after the OpenEmbedded build system has finished with them. - -```bash -INHERIT += "rm_work" -``` - -For more information please check [Here][rm_work] - -## Share sstate cache - -The directory for the shared state cache. - -```bash -SSTATE_DIR = "${HOME}/workspace_agl/sstate-cache" -``` - -For more information please check [Here][share_sstatecache] - -## Share Download directory - -The central download directory used by the build process to store downloads. - -```bash -DL_DIR = "${HOME}/workspace_agl/downloads" -``` - -For more information please check [Here][share_download] - -[buildhistory]: http://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#maintaining-build-output-quality -[rm_work]: http://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#ref-tasks-rm_work -[share_sstatecache]: https://wiki.yoctoproject.org/wiki/Enable_sstate_cache -[share_download]: http://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-DL_DIR diff --git a/docs/getting-started/image-workflow-build.md b/docs/getting-started/image-workflow-build.md new file mode 100644 index 0000000..bb2056e --- /dev/null +++ b/docs/getting-started/image-workflow-build.md @@ -0,0 +1,17 @@ +# 5. Building the AGL Image + +Building the AGL image involves running BitBake with a specified target. +Depending on whether you are building the image for the first time or if this +is a subsequent build, the time needed for the build could be significant. + +It is critical that you specify the correct options and configurations for the +build before executing the `bitbake` command. +The previous sections in the "Image Development Workflow" have treated this setup +in a generic fashion. +This section, provides links to topics with instructions needed to create images for four +supported platforms: + +* [Most Intel-based 64-Bit Boards](./machines/intel.html/overview) +* The Quick EMUlator (QEMU) +* R Car Starter Kit Gen3 Board +* Raspberry PI 2 or 3 diff --git a/docs/getting-started/image-workflow-cust-build.md b/docs/getting-started/image-workflow-cust-build.md new file mode 100644 index 0000000..2e712a5 --- /dev/null +++ b/docs/getting-started/image-workflow-cust-build.md @@ -0,0 +1,119 @@ +# 4. Customizing Your Build + +Because the build process is based on BitBake and the Yocto Project, +build customizations are driven through configuration files used during +the build. + +Lots of configuration files exist that define a build. +However, the primary one that acts as a global configuration mechanism is the +`local.conf` file, which is found in the Build Directory in a folder named "conf". + +Before you start your build process, you should open up the `local.conf` file +and look through it to be sure the general configurations are correct. +The file is well commented so you should be able to understand what the +various variables accomplish. + +To view and customize the `local.conf` file, use any text editor: + +```bash +$ vi $AGL_TOP/build/conf/local.conf +``` + +As mentioned in the "[Initializing Your Build Environment](./image-workflow-initialize-build-environment.html#initializing-your-build-environment.html)" section, +the `local.conf` file gets augmented with AGL configuration fragments based on +how you execute the `aglsetup.sh` script. +You can see those fragments at the end the configuration file. + +Even though your build should work fine after running the `aglsetup.sh` script, +you might consider editing your `local.conf` file to use one or more of the +following configurations. + +## Capturing Build History + +You can enable build history to help maintain the quality of your build output. +You can use it to highlight unexpected and possibly unwanted changes in the build output. +Basically, with build history enabled, you get a record of information about the contents +of each package and image. +That information is committed to a local Git repository where you can examine it. + +To enable build history, make sure the following two lines are in your +`local.conf` file: + +```bash +INHERIT += "buildhistory" +BUILDHISTORY_COMMIT = "1" +``` + +See the +"[Maintaining Build Output Quality](https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#maintaining-build-output-quality)" +section in the Yocto Project Reference Manual for a complete discussion on +build history. + +## Deleting Temporary Workspace + +During a build, the build system uses a lot of disk space to store temporary files. +You can ease the burden on your system and speed up the build by configuring the build +to remove temporary workspace. + +You need to inherit the `rm_work` class by using this statement in the `local.conf` file: + +```bash +INHERIT += "rm_work" +``` + +You can read about the class in the +"[rm_work.bbclass](https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#ref-classes-rm-work)" +section of the Yocto Project Reference Manual for more information. + +## Pointing at Shared State Cache Locations + +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. +When developers hit problems, they typically default back to building from scratch so they know the state +of things from the start. + +The build process uses Shared State Cache (sstate) to speed up subsequent builds. +This cache retains artifacts that can be re-used once it is determined that they +would not be different as compared to a re-built module. + +For the AGL build, you can specify the location for sstate files by including the +following in the `local.conf` file: + +```bash +SSTATE_DIR = "${HOME}/workspace_agl/sstate-cache" +``` + +also, in the `local.conf` file, you can specify additional directories in which the build +system can look for shared state information. +Use the following form in your file to list out the directories you want the build +process to look at for sstate information: + + +```bash +SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" +``` + +If you want to know more about the Yocto Project sstate mechanism, see the +"[Shared State Cache](https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#shared-state-cache)" +section in the Yocto Project Reference Manual. + +## Preserving the Download Directory + +During the initial build, the system downloads many different source code tarballs +from various upstream projects. +Downloading these files can take a while, particularly if your network +connection is slow. +The process downloads files into a +"[download directory](https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#var-DL_DIR)". +The `DL_DIR` variable defines the download directory. +For subsequent builds, you can preserve this directory to speed up the download +part of a build. + +The default download directory is in a folder named "downloads". +For the AGL build you can set the download directory by adding the following to your +`local.conf` file: + +```bash +DL_DIR = "${HOME}/workspace_agl/downloads" +``` diff --git a/docs/getting-started/image-workflow-download-sw.md b/docs/getting-started/image-workflow-download-sw.md new file mode 100644 index 0000000..ae41a34 --- /dev/null +++ b/docs/getting-started/image-workflow-download-sw.md @@ -0,0 +1,108 @@ +# 2 Downloading AGL Software + +Once you have determined the build host can build an AGL image, +you need to download the AGL source files. +The AGL source files, which includes the Yocto Project layers, are +maintained on the AGL Gerrit server. +For information on how to create accounts for Gerrit, see the +[Getting Started with AGL](https://wiki.automotivelinux.org/start/getting-started) +wiki page. + +The remainder of this section provides steps on how to download the AGL source files: + +1. **Define Your Top-Level Directory:** + You can define an environment variable as your top-level AGL workspace folder. + Following is an example that defines the `$HOME/workspace_agl` folder using + an environment variable named "AGL_TOP": + + ```bash + $ export AGL_TOP=$HOME/workspace_agl + $ mkdir -p $AGL_TOP + ``` + +2. **Download the `repo` Tool and Set Permissions:** + AGL Uses the `repo` tool for managing repositories. + Use the following commands to download the tool and then set its + permissions to allow for execution: + + ```bash + $ mkdir -p ~/bin + $ export PATH=~/bin:$PATH + $ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo + $ chmod a+x ~/bin/repo + ``` + + **NOTE:** See the + "[Repo Command Reference](https://source.android.com/setup/develop/repo)" + for more information on the `repo` tool. + +3. **Download the AGL Source Files:** + Depending on your development goals, you can either download the + latest stable AGL release branch, or the "cutting-edge" (i.e. "master" + branch) files. + + * **Stable Release:** + Using the latest stable release gives you a solid snapshot of the + latest know release. + The release is static, tested, and known to work. + To download the latest stable release branch (i.e. Flounder 6.0), use + the following commands: + + ```bash + $ cd $AGL_TOP + $ repo init -b flounder -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo + $ repo sync + ``` + + * **Cutting-Edge Files:** + Using the "cutting-edge" AGL files gives you a snapshot of the + "master" directory. + The resulting local repository you download is dynamic and can become + out-of-date with the upstream repository depending on community contributions. + The advantage of using "cutting-edge" AGL files is that you have the + absolute latest features, which are often under development, for AGL. + + To download the "cutting-edge" AGL files, use the following commands: + + ```bash + $ cd $AGL_TOP + $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo + $ repo sync + ``` + + Once you `sync` the repository, you have the AGL files in the form of + "layers" (e.g. `meta-*` folders). + You also have the `poky` repository in your AGL workspace. + + Listing out the resulting directory structure appears as follows: + + ``` + $ tree -L 1 + . + ├── build + ├── meta-agl + ├── meta-agl-demo + ├── meta-agl-devel + ├── meta-agl-extra + ├── meta-altera + ├── meta-boundary + ├── meta-freescale + ├── meta-freescale-3rdparty + ├── meta-freescale-distro + ├── meta-intel + ├── meta-intel-iot-security + ├── meta-oic + ├── meta-openembedded + ├── meta-qcom + ├── meta-qt5 + ├── meta-raspberrypi + ├── meta-renesas + ├── meta-renesas-rcar-gen3 + ├── meta-rust + ├── meta-sdl + ├── meta-security-isafw + ├── meta-ti + ├── meta-updater + ├── meta-virtualization + └── poky + ``` diff --git a/docs/getting-started/image-workflow-initialize-build-environment.md b/docs/getting-started/image-workflow-initialize-build-environment.md new file mode 100644 index 0000000..eed41e7 --- /dev/null +++ b/docs/getting-started/image-workflow-initialize-build-environment.md @@ -0,0 +1,255 @@ +# 3. Initializing Your Build Environment + +Part of the downloaded AGL software is a setup script that you must +run to initialize the build environment. + +## `aglsetup.sh` Script + +You can find this script here: + +``` +$AGL_TOP/meta-agl/scripts/aglsetup.sh +``` + +The script accepts many options that allow you to define build parameters such +as the target hardware (i.e. the machine), build directory, and so forth. +Use the following commands to see the available options and script syntax: + +``` +$ bash +$ cd $AGL_TOP +$ source meta-agl/scripts/aglsetup.sh -h +``` + +## AGL Features + +Before running the `aglsetup.sh`, you should understand what AGL features you +want to include as part of your image. +The script's help output lists available features and shows you the layers in +which they reside. + +Following is a list of the available features: + +``` +Available features: + [meta-agl] + agl-all-features :( agl-demo agl-appfw-smack agl-devel agl-hmi-framework agl-netboot agl-sota agl-sdl ) + agl-appfw-smack + agl-archiver + agl-ci + agl-ci-change-features :( agl-demo agl-appfw-smack agl-devel agl-hmi-framework agl-devel agl-netboot agl-appfw-smack agl-sdl ) + agl-ci-change-features-nogfx :( agl-devel agl-netboot agl-appfw-smack ) + agl-ci-snapshot-features :( agl-demo agl-appfw-smack agl-devel agl-hmi-framework agl-devel agl-netboot agl-appfw-smack agl-archiver agl-sdl agl-ptest ) + agl-ci-snapshot-features-nogfx :( agl-devel agl-netboot agl-appfw-smack agl-isafw agl-archiver agl-ptest ) + agl-devel + agl-isafw + agl-netboot + agl-ptest + agl-sota + [meta-agl-demo] + agl-demo :( agl-appfw-smack agl-devel agl-hmi-framework ) + agl-iotivity + agl-sdl + [meta-agl-devel] + agl-audio-4a-framework + agl-audio-soundmanager-framework + agl-egvirt + agl-hmi-framework + agl-oem-extra-libs + agl-renesas-kernel + [meta-agl-extra] + agl-localdev + eas +``` + +To find out exactly what a feature provides, **WE NEED SOME GUIDANCE HERE. MAYBE SOME INDIVIDUAL README FILES LOCATED IN THE TEMPLATE AREAS FOR THE FEATURES**. + +An AGL feature is a configuration that accounts for specific settings +and dependencies needed for a particular build. +For example, specifying the "agl-demo" feature makes sure that the +`aglsetup.sh` script creates configuration files needed to build the +image for the AGL demo. + +Following are brief descriptions of the AGL features you can specify on the +`aglsetup.sh` command line: + +* **agl-all-features**: A set of AGL default features. + Do not think of this set of features as all the AGL features. + +* **agl-appfw-smack**: Enables IoT.bzh Application Framework plus SMACK and + Cynara. + +* **agl-archiver**: Enables the archiver class for releases. + +* **agl-ci**: Flags used for Continuous Integration (CI). + Using this feature changes the value of the + [`IMAGE_FSTYPES`](https://yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#var-IMAGE_FSTYPES) + variable. + +* **agl-ci-change-features**: Enables features for CI builds for Gerrit changes. + +* **agl-ci-change-features-nogfx**: Enables features for CI builds for Gerrit changes + for targets that use binary graphics drivers (i.e. builds without graphics). + +* **agl-ci-snapshot-features**: Enables features for CI daily snapshot builds. + +* **agl-ci-snapshot-features-nogfx**: Enables features for CI daily snapshot builds for + targets that use binary graphics drivers (i.e. builds without graphics). + +* **agl-devel**: Activates development options such as an empty root password, + debuggers, strace, valgrind, and so forth. + +* **agl-isafw**: Enables an image security analysis framework. + **NOTE:** This feature is deprecated. + +* **agl-netboot**: Enables network boot support through Trivial File Transfer Protocol (TFTP) and Network Block Device (NBD) protocol. + Netboot is needed for CI and useful for development to avoid writing + sdcards. Needs additional setup. + +<!-- +* **agl-profile**: A group or set of Layers and a Package Group as used + by the Yocto Project. + This feature helps define dependency for various profiles and layers + used during the build. + For example, "agl-demo" depends on "agl-profile-graphical-qt", which + in turn depends on "agl-profile-graphical", which in turn depends + on "agl-profile-core". + + agl-profile-graphical + agl-profile-graphical-html5 + agl-profile-graphical-qt5 + agl-profile-hud + agl-profile-telematics + + **NOTE:** For information on Package Groups, see the + "[Customizing Images Using Custom Package Groups](https://www.yoctoproject.org/docs/2.4.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks)" + section in the Yocto Project Development Tasks Manual. + You can also find general information about Layers in the + "[Layers](https://www.yoctoproject.org/docs/2.4.4/dev-manual/dev-manual.html#yocto-project-layers)" + section in that same manual. +--> + +* **agl-ptest**: Enables + [Ptest](https://yoctoproject.org/docs/2.4.4/dev-manual/dev-manual.html#testing-packages-with-ptest) + as part of the build. + +* **agl-sota**: Enables State of the Art (SOTA) components and dependencies. + Includes meta-sota, meta-file systems, meta-ruby, and meta-rust. + +* **agl-demo**: Enables the layers meta-agl-demo and meta-qt5. + You need agl-demo if you are going to build the agl-demo-platform. + +* **agl-iotivity**: Enables iotivity such as status unclear, needs check, and needs removal. + +* **agl-sdl**: Enables or adds SDL to the build. + +* **agl-audio-4a-framework**: Enables AGL advanced audio architecture, which is an exclusive switch for audio framework. + +* **agl-audio-soundmanager-framework**: Enables Soundmanager framework, which is an exclusive switch for audio framework. + +* **agl-egvirt**: Enables virtualization support for the R-Car. + +* **agl-hmi-framework**: Enables HMI framework. + HMI framework is enabled by default. + +* **agl-oem-extra-libs**: Pulls in additional libraries. + **NOTE:** This feature is under construction. + It needs further work and testing. + +* **agl-renesas-kernel**: Enables renesas-specific kernel options. + +* **agl-telemetry**: Enables the telemetry demo. To use this feature, + you must convert it into agl-profile-telematics. + **NOTE:** agl-telemetry is not in the layer. + +* **agl-localdev**: Adds a local layer named "meta-localdev" in the + meta directory and a local.dev.inc configuration file when that file + is present. + + This feature provides a shortcut for using the layer meta-localdev + in the top-level folder for easy modifications to your own recipes. + +* **eas**: I don't know what this does. + +## Example + +Following is an example that initializes the build environment, selects "beaglebone" +for the machine, and chooses the "agl-demo" feature, which also includes the +"agl-appfw-smack", "agl-devel", and "agl-hmi-framework" features: + +``` +$ source meta-agl/scripts/aglsetup.sh -m beaglebone agl-demo +aglsetup.sh: Starting +Generating configuration files: + Build dir: /home/scottrif/workspace_agl/build + Machine: beaglebone + Features: agl-appfw-smack agl-demo agl-devel agl-hmi-framework + Running /home/scottrif/workspace_agl/poky/oe-init-build-env + Templates dir: /home/scottrif/workspace_agl/meta-agl/templates/base + Config: /home/scottrif/workspace_agl/build/conf/bblayers.conf + Config: /home/scottrif/workspace_agl/build/conf/local.conf + Setup script: /home/scottrif/workspace_agl/build/conf/setup.sh + Executing setup script ... --- beginning of setup script + fragment /home/scottrif/workspace_agl/meta-agl/templates/base/01_setup_EULAfunc.sh + fragment /home/scottrif/workspace_agl/meta-agl/templates/base/99_setup_EULAconf.sh + end of setup script +OK +Generating setup file: /home/scottrif/workspace_agl/build/agl-init-build-env ... OK +aglsetup.sh: Done + + Shell environment set up for builds. + +You can now run 'bitbake target' + +Common targets are: + - meta-agl: (core system) + agl-image-minimal + agl-image-minimal-qa + + agl-image-ivi + agl-image-ivi-qa + agl-image-ivi-crosssdk + + agl-image-weston + + - meta-agl-demo: (demo with UI) + agl-demo-platform (* default demo target) + agl-demo-platform-qa + agl-demo-platform-crosssdk + + agl-demo-platform-html5 +$ +``` + +Running the script creates the Build Directory if it does not already exist. +For this example, the Build Directory is "$AGL_TOP/workspace_agl/build". + +The script's output also indicates the machine and AGL features selected for the build. + +The script creates two primary configuration files used for the build: `local.conf` and `bblayers.conf`. +Both these configuration files are located in the Build Directory in the `conf` folder. +If you were to examine these files, you would find standard Yocto Project +configurations along with AGL configuration fragments, which are driven by the +machine (i.e. beaglebone) and the AGL features specified as part of the +script's command line. + +The end result is configuration files specific for your build in the AGL development environment. + +Finally, part of the `aglsetup.sh` script makes sure that any End User License Agreements (EULA) +are considered. +You can see that processing in the script's output as well. + +**NOTE:** Use of the `local.conf` and `bblayers.conf` configuration files is fundamental +in the Yocto Project build environment. +Consequently, it is fundamental in the AGL build environment. +You can find lots of information on configuring builds in the Yocto Project +documentation set. +Here are some references if you want to dig into configuration further: + +* [Customizing Images Using local.conf](https://yoctoproject.org/docs/2.4.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-localconf) +* [Local](https://yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#ref-varlocality-config-local) +* [build/conf/local.conf](https://yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#structure-build-conf-local.conf) +* [build/conf/bblayers.conf](https://yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf) +* [BBLAYERS](https://yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#var-BBLAYERS) +* [User Configuration](https://yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#user-configuration) +* [Enabling Your Layer](https://yoctoproject.org/docs/2.4.4/dev-manual/dev-manual.html#enabling-your-layer) diff --git a/docs/getting-started/image-workflow-intro.md b/docs/getting-started/image-workflow-intro.md new file mode 100644 index 0000000..ad36d01 --- /dev/null +++ b/docs/getting-started/image-workflow-intro.md @@ -0,0 +1,31 @@ +# Overview # + +The AGL image development workflow consists of setting up +the system (i.e. the build host) that builds the image and finishes with +using the +[Yocto Project](https://yoctoproject.org) to create an image +targeted towards specific hardware. + +The following figure and list overview the AGL image development +process. +You can learn about the steps in the process by reading through the +remaining sections. + +**NOTE:** This procedure uses information from many other procedures +in the AGL Documentation set. +Links are provided when a set of steps is required that is documented +elsewhere. + +<center><img src="images/image-developer-workflow.png"></center> + +1. Prepare your build host to use use the tools needed to build your image. + +2. Download the AGL software into a local Git repository on your build host. + +3. Run the build environment script to initialize variables and paths needed for the build. + +4. Make sure your build configuration is defined exactly how you want it for your build. + +5. Use + [BitBake](https://yoctoproject.org/docs/2.4.4/bitbake-user-manual/bitbake-user-manual.html) + to build your image. diff --git a/docs/getting-started/image-workflow-prep-host.md b/docs/getting-started/image-workflow-prep-host.md new file mode 100644 index 0000000..1205ac0 --- /dev/null +++ b/docs/getting-started/image-workflow-prep-host.md @@ -0,0 +1,76 @@ +# 1. Preparing Your Build Host + +Preparing your build host so that it can build an AGL image means +making sure your system is set up to use the +[Yocto Project](https://yoctoproject.org) OpenEmbedded build system, +which is based on +[BitBake](https://yoctoproject.org/docs/2.4.4/bitbake-user-manual/bitbake-user-manual.html). + +This section presents minimal information so you can prepare the build host +to use the "Rocko" version of the Yocto Project (i.e. version 2.4.4). +If you want more details on how the Yocto Project works, you can reference +the Yocto Project documentation +[here](https://www.yoctoproject.org/docs/). + +**NOTE:** This entire section presumes you want to build an image. +You can skip the entire build process if you want to use a ready-made +development image. +The +[supported images][AGL snapshots master latest] exist for several boards as +well as for the Quick EMUlator (QEMU). +See the +"[Downloading an Image](./app-workflow-image.html#downloading-an-image)" +section for more information on the ready-made images. + +1. **Use a Supported Linux Distribution:** To use the AGL software, it is + recommended that your build host is a native Linux machine that runs a + Yocto Project supported distribution as described by the + "[Supported Linux Distributions](https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#detailed-supported-distros)" + section in the Yocto Project Reference Manual. + Basically, you should be running a recent version of Ubuntu, Fedora, openSUSE, + CentOS, or Debian. + + If you must use a build host that is not a native Linux machine, you can + install and use a Docker container. + The container contains the same development environment (i.e. distros, packages, + and so forth) as would a properly prepared build host running a supported + Linux distribution. + For information on how to install and set up this Docker container, see the + "[AGL SDK Quick Setup](./setup-sdk-environment.html#step-1-install-docker)" + section. + +2. **Be Sure Your Build Host Has Enough Free Disk Space:** + Your build host should have at least 50 Gbytes. + +3. **Be Sure Tools are Recent:** You need to have recent versions for + the following tools: + + * Git 1.8.3.1 or greater + * Tar 1.27 or greater + * Python 3.4.0 or greater + + If your distribution does not meet these minimal requirements, see the + "[Required Git, tar, and Python Versions](https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#required-git-tar-and-python-versions)" + section in the Yocto Project Reference Manual for steps that you can + take to be sure you have these tools. + +4. **Install Essential, Graphical, and Eclipse Plug-in Build Host Packages:** + Your build host needs certain host packages. + Depending on the Linux distribution you are using, the list of + host packages differ. + See + "[The Build Host Packages](https://www.yoctoproject.org/docs/2.4.4/yocto-project-qs/yocto-project-qs.html#packages)" + section of the Yocto Project Quick Start for information on the packages you need. + + **NOTE:** If you are using the CentOS distribution, you need to + separately install the epel-release package and run the `makecache` command as + described in + "[The Build Host Packages](https://www.yoctoproject.org/docs/2.4.4/yocto-project-qs/yocto-project-qs.html#packages)" + section of the Yocto Project Quick Start. + + Aside from the packages listed in the previous section, you need the following: + + * **Ubuntu and Debian:** curl + * **Fedora:** curl + * **OpenSUSE:** glibc-locale curl + * **CentOS:** curl diff --git a/docs/getting-started/images/image-developer-workflow.png b/docs/getting-started/images/image-developer-workflow.png Binary files differnew file mode 100644 index 0000000..daaeda0 --- /dev/null +++ b/docs/getting-started/images/image-developer-workflow.png diff --git a/docs/getting-started/machines/intel.md b/docs/getting-started/machines/intel.md index 34957a8..74988a1 100644 --- a/docs/getting-started/machines/intel.md +++ b/docs/getting-started/machines/intel.md @@ -1,186 +1,153 @@ -# Running AGL on Intel MinnowBoard (and most Intel 64 bits HW) - -## Scope - -This documentation is aiming at people who want to run Automotive Grade -Linux (AGL) on Intel Hardware (HW). -While the reference HW used by AGL project is the Open Source MinnowBoard, this documentation [MinnowBoard wiki](https://minnowboard.org/) can be used to enable most of 64-bit Intel Architecture (IA) platforms using UEFI as boot loader. -In addition to the MinnowBoard, support for the [upCore & UpSquared boards](http://www.up-board.org/upsquared/) has been added. -You need to run the 64-bit version of the UEFI bootloader. +# Building for Most Intel 64-Bit Hardware Platforms + +Although the reference hardware used by the AGL Project is the 64-bit Open Source MinnowBoard, +you can use the information found on the "[MinnowBoard wiki](https://minnowboard.org/)" +to enable most 64-bit Intel Architecture (IA) platforms that use the 64-bit +UEFI as the boot loader. +In addition to the MinnowBoard, support for the +[upCore & UpSquared boards](http://www.up-board.org/upsquared/) exists. MinnowBoard Max and Turbot as well as Joule are both 64-bit capable. -**Note**: This page is more focused on those who want to create bespoke AGL images and BSPs. - -If you are interested in creating ***applications*** to run on AGL, please visit the [Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps) documentation. - -UEFI has evolved a lot recently and you likely want to check that your HW firmware is up-to-date, this is mandatory for both the MinnowBoard-Max and the Joule. Not required on Minnowboard-Turbo and Up boards. - -[`https://firmware.intel.com/projects/minnowboard-max`](https://firmware.intel.com/projects/minnowboard-max) -[`https://software.intel.com/en-us/flashing-the-bios-on-joule`](https://software.intel.com/en-us/flashing-the-bios-on-joule) - -## Where to find an AGL bootable image +If you are interested in creating ***applications*** to run on hardware booted +using an image built with the AGL Project, see the following: -### Download a ready made image - -AGL provides ready made images for developers. -You will find them on [AGL Download web site](https://download.automotivelinux.org/AGL/release) -image are located in YourPreferedRelease/intel-corei7-64/deploy/images/intel-corei7-64/ -Create a bootable SD card with the script [mkefi-agl.sh](https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git;a=blob_plain;f=scripts/mkefi-agl.sh;hb=HEAD) -check the available options with the -v option. mkefi-agl.sh -v - -### Building an AGL image from scratch using Yocto - -**Note**: an alternative method for building an image is to use the AGL SDK delivered in a Docker container. - -There is currently no SDK dedicated to IA but the SDK provided for the Porter Board can build an IA image without changes (just `aglsetup.sh` needs to call for Intel). +* [Application Development Workflow](../../../app-workflow-intro.html/overview) +* [Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps) -See chapter 2 of [Porter QuickStart](http://iot.bzh/download/public/2016/sdk/AGL-Kickstart-on-Renesas-Porter-board.pdf "wikilink"). +UEFI has significantly evolved and you will likely want to check that your hardware's +firmware is up-to-date. +You should make this check for both the MinnowBoard-Max and the Joule platforms. +You do not need to make this check for the MinnowBoard-Turbo and Up platforms: -#### Download AGL source code +* [`https://firmware.intel.com/projects/minnowboard-max`](https://firmware.intel.com/projects/minnowboard-max) +* [`https://software.intel.com/en-us/flashing-the-bios-on-joule`](https://software.intel.com/en-us/flashing-the-bios-on-joule) -Downloading the AGL sources from the various Git repositories is automated with the `repo` tool. Basic steps to download the AGL source code is described below and for more advanced topics involving the `repo` tool, please refer to the [`repo` documentation](https://source.android.com/source/using-repo.html "wikilink"). +## 1. Making Sure Your Build Environment is Correct -To install the `repo` tool: +The +"[Initializing Your Build Environment](../../../image-workflow-initialize-build-environment.html/Initializing-your-build-environment)" +section presented generic information for setting up your build environment +using the `aglsetup.sh` script. +If you are building for an Intel 64-bit platform, you need to specify some +specific options when you run the script: ```bash - mkdir -p ~/bin; - export PATH=~/bin:$PATH; - curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo; - chmod a+x ~/bin/repo; +$ source meta-agl/scripts/aglsetup.sh \ + -m intel-corei7-64 \ + agl-devel agl-demo agl-appfw-smack agl-netboot agl-audio-4a-framework ``` -#### Configuring for the current *(older)* stable (Electric Eel 5.0.x) - -```bash - cd AGL-5.0.x; - repo init -b eel -m default.xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -``` +The "-m" option specifies the "intel-corei7-64" machine. +If you were building for a Joule developer kit, you would use the +"-m joule" option. -#### Configuring for master (DD) +The list of AGL features used with script are appropriate for the AGL demo image suited +for the Intel 64-bit target. +The "agl-netboot" option creates the correct Initial RAM Filesystem (initramfs) +image even if you do not boot from a network. -```bash - cd AGL-master; - repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo; -``` +## 2. Using BitBake -Once that you repo is initialised either with the stable or WIP, you need to sync the repo to fetch the various git trees. +This section shows the `bitbake` command used to build the AGL image. +Before running BitBake to start your build, it is good to be reminded that AGL +does provide pre-built images for developers that work with supported hardware. +You can find these pre-built images on the +[AGL Download web site](https://download.automotivelinux.org/AGL/release). -#### Downloading the configured AGL source code +For supported Intel images, the filenames have the following form: -```bash - repo sync; ``` - -#### Building the AGL distro - -You are now ready to initialise your Yocto build. -When running the command: - -```bash - source meta-agl/scripts/aglsetup.sh -h +<release-name>/<release-number>/intel-core17-64/deploy/images/intel-core17-64/bzImage-intel-corei7-64.bin ``` -You will notice the Intel entries +Start the build using the `bitbake` command. +**NOTE:** An initial build can take many hours depending on your +CPU and and Internet connection speeds. +The build also takes approximately 100G-bytes of free disk space. -```bash - intel-corei7-64 - joule -``` - -Simply select that entry to replace porter in the -m option. -**Note:** agl-netboot option is required to create the right initramfs even if you do not boot from a network - -```bash - source meta-agl/scripts/aglsetup.sh \ - -m intel-corei7-64 \ - -b build \ - agl-devel agl-demo agl-appfw-smack agl-netboot agl-audio-4a-framework -``` - -**Note:** use the option "-m joule" when building for a Joule developer Kit target. - -Start the build **This can take several hours depending of your CPU and -internet connection and will required several GB on /tmp as well as on your build directory** +For this example, the target is "agl-demo-platform": ```bash bitbake agl-demo-platform ``` -**Your newly baked disk image (.wic.xz) will be located at**: - `tmp/deploy/images/intel-corei7-64/` - -##### Alternative: Download a *ready made* image from AGL web site - -The Continuous Integration (CI) process from AGL creates and publish daily and stable builds. -Pointers to both can be found in [AGL supported HW](https://wiki.automotivelinux.org/agl-distro) (see Reference BSP/Intel). +The build process puts the resulting image in the Build Directory: -Once you have validated your process you can start to play/work with the snapshot pointer. - -Note that snapshot build may not work. +``` +<build_directory>/tmp/deploy/images/intel-corei7-64/ +``` -Follow the directory: +**WRITER NOTE:** I am not sure what to do with the following information: -`intel-corei7-64/deploy/images/intel-corei7-64/` +An alternative method for building an image is to use the AGL SDK delivered in a Docker container. -and download the file: +There is currently no SDK dedicated to IA but the SDK provided for the Porter Board can build an IA image without changes (just `aglsetup.sh` needs to call for Intel). -`agl-demo-platform-intel-corei7-64.hddimg` +See chapter 2 of [Porter QuickStart](http://iot.bzh/download/public/2016/sdk/AGL-Kickstart-on-Renesas-Porter-board.pdf "wikilink"). -## Create a bootable media +## 3. Creating Bootable Media -Depending your target HW you will use an USB stick, an SD card or a HDD/SDD. +Depending your target hardware you will use an USB stick, an SD card or a HDD/SDD. The creation process remains the same independently of the selected support. It does require to have access to a Linux machine with `sudo` or root password. -### Insert you removable media in the corresponding interface - -### Check the device name where the media can be accessed with the command - -```bash - lsblk - # Note that you want the name of the raw device not of a partition on the media - #(eg. /dev/sdc or /dev/mmcblk0) -``` +Create a bootable SD card with the script [mkefi-agl.sh](https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git;a=blob_plain;f=scripts/mkefi-agl.sh;hb=HEAD) +check the available options with the -v option. mkefi-agl.sh -v -### Download the script `mkefi-agl.sh` +1. **Insert Media Device:** + Insert your removable media into the corresponding interface. -This script is present in the directory meta-agl/scripts from blowfish 2.0.4 : [mkefi-agl.sh](https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git;a=blob_plain;f=scripts/mkefi-agl.sh;hb=HEAD) +2. **Determine the Name of Your Media Device:** + Use the `lsblk` command to make sure you know the name of the device to which you will be writing. -Alternatively you can download it from the following Git repo: + ```bash + lsblk + # You want the name of the raw device and not the name of a partition on the media. + #(e.g. /dev/sdc or /dev/mmcblk0) + ``` -[https://github.com/dominig/mkefi-agl.sh](https://github.com/dominig/mkefi-agl.sh) +3. **Download the `mkefi-agl.sh` Script:** + You can find the script in the "meta-agl/scripts" folder of your AGL source files. -### check the available options + Alternatively, you can download the script from the following Git repository: -```bash - sh mkefi-agl.sh -v; -``` + [https://github.com/dominig/mkefi-agl.sh](https://github.com/dominig/mkefi-agl.sh) -### create your media with the command adjusted to your configuration +4. **Create Your Bootable Media:** + Run the following to see `mkefi-agl.sh` usage information: -```bash - sudo sh mkefi-agl.sh MyAglImage.hdd /dev/sdX - #/dev/sdX is common for USB stick, /dev/mmcblk0 for laptop integrated SD card reader -``` + ```bash + ./mkefi-agl.sh -v + ``` -## Boot the image on the target device + Supply the name of your actual image and device name and run the script. + The following example assumes a USB device (e.g. `/dev/sdb`) and the image + `intel-corei7-64.hdd`: -1. Insert the created media with the AGL image in the target device + ```bash + $ sudo ./mkefi-agl.sh intel-corei7-64.hdd /dev/sdb + # /dev/sdX is common for USB stick where "X" is "b". + # /dev/mmcblk0 is common for an integrated SD card reader in a notebook computer. + ``` -1. Power on the device +## 4. Booting the Image on the Target Device -1. Select Change one off boot option (generally F12 key during power up) +Follow these steps to boot your image on the target device: -1. Select your removable device +1. Insert the bootable media that contains the AGL image into the target device. -1. Let AGL boot +2. Power on the device. -**Note:**: depending on the speed of the removable media, the first boot may not complete, in that case simply reboot the device. +3. As the device boots, access the boot option screen. + You generally accomplish this with the F12 key during the power up operation. -This is quite common with USB2 sticks. +4. From the boot option screen, select your bootable media device. -By default the serial console is configured and activated at the rate of 115200 bps. +5. Save and exit the screen and let the device boot from your media. -## How to create your 1st AGL application + **NOTE:**: Depending on the speed of your removable media, the first boot might + not complete. + If this is the case, reboot the device a second time. + It is common with USB sticks that you need to boot a couple of times. -[Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps) + For Intel devices, the serial console is configured and activated at the rate of 115200 bps. diff --git a/docs/getting-started/source-code.md b/docs/getting-started/source-code.md deleted file mode 100644 index 3c5d6f4..0000000 --- a/docs/getting-started/source-code.md +++ /dev/null @@ -1,201 +0,0 @@ -# Introduction: Building target AGL image with Yocto project - -The standard Yocto process is made of the following steps: - -* Setting up your operating system. -* Setting up the build environment for R-Car BSP. -* Downloading the proprietary drivers and installing them in the build environment (if needed). -* Build the image. -* Boot using SD-CARD. - * Create an SD-CARD. - * Configure to boot on SD-CARD. - * Copy the image to the SD-CARD. - * Boot the board on it. - -For convenience, the resulting development images are made available [Here][AGL snapshots master latest] - -If you want to bypass the build phase and quick boot the board, you can download the image tarball and the kernel then follow the installation procedure. - -## Setting up your operating system - -The very first step is to ensure that your system can run the build system of the Yocto Project. - -**Important**: it only runs on Linux - -* if your system is Windows© or iOS© you should use a virtualization solution (Virtualbox, VMWare ...) to run a Linux VM on your system. - -For AGL 6.0, Yocto Project 2.4, known as rocko, has been selected for the BSP and build system. - -Reference data for configuring your system can be found in the Yocto documentation [Here][yocto ref Manual] - -Here after an extract of this documentation for most common Linux distributions: - -* The build system should be able to run on any modern distributions that has the following versions for: - * Python - * Git 1.7.8 or greater - * tar 1.24 or greater - * GCC, … - -**Note**: - -* Python 2.7.3 or greater excluding Python 3.x, which is not supported. - -### Ubuntu and Debian - -The essential and graphical support packages you need for a supported Ubuntu or Debian distribution are shown in the following command: - -```bash -sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \ - build-essential chrpath socat libsdl1.2-dev xterm cpio curl -``` - -**Note**: - -* Also note that for this tutorial, the utility 'curl' has been added to the list of packages to install. - -### Fedora - -The essential and graphical packages you need for a supported Fedora distribution are shown in the following command: - -```bash -sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ - diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ - ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue socat \ - SDL-devel xterm curl -``` - -### OpenSUSE - -The essential and graphical packages you need for a supported OpenSUSE distribution are shown in the following command: - -```bash -sudo zypper install python gcc gcc-c++ git chrpath make wget python-xml \ - diffstat texinfo python-curses patch socat libSDL-devel xterm curl \ - python3 python3-curses glibc-locale -``` - -### CentOS - -The essential and graphical packages you need for a supported CentOS distribution are shown in the following command: - -```bash -sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ - diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ - socat SDL-devel xterm curl -``` - -## Download AGL Source Code - -The AGL source code and Yocto layers are maintained on the AGL Gerrit server. -For information on how to create accounts for gerrit see [Getting Started with AGL][Getting Started with AGL]. - -### Setting up the build environment - -In the following, your top level directory is noted as “AGL_TOP”. -For example, we will set AGL_TOP to point to a directory “$HOME/workspace_agl”: - -```bash -export AGL_TOP=$HOME/workspace_agl -mkdir -p $AGL_TOP -``` - -### Prepare Repo Tool - -AGL Uses the 'repo' tool for managing repositories. -You need to setup layers of AGL. -You can use the commands below to prepare Repo: - -```bash -mkdir -p ~/bin -export PATH=~/bin:$PATH -curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo -chmod a+x ~/bin/repo -``` - -**Note**: - -* More information about the tool 'repo' [Here][repo info] - -### Download source - -You can choose your source release - -### Download Latest Stable Release - -To download all layers for the for the latest stable release, eel 5.0.3: - -```bash -cd $AGL_TOP -repo init -b eel -m eel_5.1.0.xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -repo sync -``` - -### Download Master Branch - -To download all code from master: - -```bash -cd $AGL_TOP -repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -repo sync -``` - -## Set up Build Environment Info - -AGL has created a set up script for defining the target build and desired optional features. - -To get a complete list of the options available run. - -```bash -cd $AGL_TOP -source meta-agl/scripts/aglsetup.sh -h -``` - -Once you run aglsetup.sh with your desired parameters, you can build any target desired. - -## Features supported by aglsetup - -Here is the list of features for AGL 2.1 that can be specified in the aglsetup.sh command line: - -* in **meta-agl** - * agl-all-features - * agl-appfw-smack: enables IoT.bzh Application Framework + SMACK + Cynara - * agl-archiver - * agl-ci - * agl-ci-change-features - * agl-ci-change-features-nogfx - * agl-ci-snapshot-features - * agl-ci-snapshot-features-nogfx - * agl-devel: activate development options (empty root password, debugger, strace, valgrind …) - * agl-gplv2 - * agl-isafw - * agl-netboot: enable network boot support through TFTP and NBD (see meta-netboot layer) - * agl-profile-graphical - * agl-profile-graphical-html5 - * agl-profile-graphical-qt5 - * agl-profile-hud - * agl-profile-telematics - * agl-ptest - * agl-sota: enable SOTA components and dependencies (meta-sota, meta-filesystems, meta-ruby, meta-rust are added) -* in **meta-agl-demo** - * agl-demo: enable layer meta-agl-demo and meta-qt5 - required to build * agl-demo-platform - * agl-iotivity - * agl-sdl -* in **meta-agl-devel** - * agl-audio-4a-framework - * agl-audio-soundmanager-framework - * agl-egvirt - * agl-hmi-framework - * agl-oem-extra-libs - * agl-renesas-kernel - * agl-telemetry -* in **meta-agl-extra** - * agl-localdev: add a local layer named “meta-localdev” in meta directory and a local.dev.inc conf file if present - * blsched - -For newer features or to get more details on a given feature, take a look at the configuration files stored for each feature and/or each machine in meta-agl/templates and meta-agl-extra/templates. - -[AGL snapshots master latest]: https://download.automotivelinux.org/AGL/snapshots/master/latest/ -[yocto ref Manual]: http://www.yoctoproject.org/docs/2.0/ref-manual/ref-manual.html#detailed-supported-distros -[Getting Started with AGL]: https://wiki.automotivelinux.org/start/getting-started -[repo info]: https://source.android.com/source/using-repo.html |
