aws4embeddedlinux-ci-examples

Getting Started

This repository shows ways to use the aws4embeddedlinux-ci library.

In order to use these examples, you must set up the CDK, including installing the CDK tool and bootstrapping the account you wish to deploy to. Additionally, you must have Node installed.

Note

This library is tested against Node Versions 16, 18, and 20. If these versions are not available for your system, we recommend using NVM to install a compatible version.

Clone and Setup NPM Project

git clone https://github.com/aws4embeddedlinux/aws4embeddedlinux-ci-examples.git
cd aws4embeddedlinux-ci-examples
npm install .
npm run build

Note that while the CDK projects often do not require that you invoke the build command separately, doing so will ensure various assets in the library are packaged correctly.

Deploying

To deploy all the pipeline examples, you can use the CDK deploy command:

cdk deploy --all

Alternatively, to deploy just a specific pipeline example, you can use the CDK deploy command:

<EXAMPLE> can be one or more of: PokyPipeline, QemuEmbeddedLinuxPipeline, PokyAmiPipeline, KasPipeline, RenesasPipeline, NxpImxPipeline

cdk deploy <EXAMPLE>

The pipelines can be found in the Developer Tools > Code Pipeline > Pipelines Console page. The newly created pipeline ubuntu_22_04BuildImagePipeline should start automatically. If not, it will need to be run before other pipelines will work correctly. Once it is complete, the EmbeddedLinuxPipeline in the CodePipeline console page is ready to run.

Removing Pipelines

The cdk destroy command can be used to remove individual pipelines and their related resources. This can also be done in the CloudFormation Console Page. Do not delete stacks while a CodePipeline is running, this can lead to unexpected failures!

To remove all the resources associated with this application:

cdk destroy --all

Examples

Several example pipelines are provided. Each one demonstrates a different aspect of how to build a Yocto image with AWS.

A Simple Poky Based Pipeline

This example will build the core-image-minimal image from Poky using the repo tool to manage layers. CVE checking is also enabled in the buildspec file.

The recommended place to view this is from the Developer Tools > Code Pipeline > Pipelines page. The pipeline will start with PokyPipeline- followed by some unique identifier. From the pipeline page, you can find the CodeCommit source repository, the CodeBuild Project (with build logs), and the S3 bucket that the image is uploaded to, at the end.

Example stack name: PokyPipeline

Expected build time: 32min / rebuild (without any change, just use sstate cache): 8min

Using Kas

The Kas example shows how to use a Kas Config to manage layers. This tool can help programatically manage layers and config with tighter Yocto integration than Git Submodules or the Repo tool.

See the AWS CodeBuild pipeline: KasPipeline-EmbeddedLinuxPipeline*

Example stack name: KasPipeline

Expected build time: 36min / rebuild (without any change, just use sstate cache): 11min

A slightly modified version building a qemu pipeline:

This example builds a Qemu based image using meta-aws-demos. The Qemu image can be run in the CodeBuild environment. Using SLIRP networking, OEQA testing such as ptest can be run in the pipeline.

See the AWS CodeBuild pipeline: QemuEmbeddedLinuxPipeline-EmbeddedLinuxPipeline*

Expected build time: 45min / rebuild (without any change, just use sstate cache): 14min

A Poky Based EC2 AMI Pipeline

Yocto can be used to create an EC2 AMI. This example builds an AMI based on Poky and meta-aws and exports it to your AMI registry using the VM Import/Export Service.

The pipeline name starts with PokyAmiPipeline- in the CodePipeline page.

Example stack name: PokyAmiPipeline

Expected build time: 52min / rebuild (without any change, just use sstate cache): 17min

A NXP / IMX Pipeline

This example will build an image for the i.MX 6ULL EVK board.

NXP requires users to accept and comply with a EULA in order to build and, for this reason, the buildspec will require modification before the build succeeds. See the IMX Yocto Users Guide for more detail.

The pipeline name starts with NxpImxPipeline- in the CodePipeline page.

Example stack name: NxpImxPipeline

Using pre-built, proprietary artifacts in a Pipeline

This example is based on this work to build an image for Renesas R-Car-H3 Starter Kit Premier board (unofficial name - H3ULCB) including the proprietary graphics and multimedia drivers from Renesas.

Download the Multimedia and Graphics library and related Linux drivers from the following link (registration necessary): https://www.renesas.com/us/en/application/automotive/r-car-h3-m3-h2-m2-e2-documents-software

Download two files:

• R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-20220121.zip
• R-Car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-20220121.zip

Graphic drivers are required for Wayland. Multimedia drivers are optional.

Steps to build the image

1. Create a folder named proprietary in the root of the source repo, and put those two downloaded files into this folder.
2. Deploy the build pipeline and uncomment the #TODO in the build.sh file.
3. A build should automatically start. Once it succeeds you will get an image containing the proprietary graphics and multimedia drivers.

See the AWS CodeBuild pipeline: RenesasPipeline-EmbeddedLinuxPipeline*

Example stack name: RenesasPipeline

Expected build time: 27min / rebuild (without any change, just use sstate cache): 9min

A AWS CodeBuild Project

This will create an Embedded Linux ready AWS CodeBuild project that can be used to connect to a source, e.g. GitHub Actions. This is not using any CodePipeline.

And use the EFS to share downloads and sstate cache between the runners.

The connection to the CodeBuild source must be performed manually.

Also you can clone the CodeBuild project and share the efs between the CodeBuild projects.

See the AWS CodeBuild pipeline: EmbeddedLinuxCodebuildProje-*

To make a source connection to GitHub you need to:

• Select a "Source provider"->"GitHub"
• Select "Primary source webhook events" -> "Webhook - optional" -> "Rebuild every time a code change is pushed to this repository"
• Add "Filter group 1" -> "WORKFLOW_JOB_QUEUED"
• Modify the GitHub action runs-on: ${{ vars.CODEBUILD_RUNNER_NAME }}-${{ github.run_id }}-${{ github.run_attempt }} CODEBUILD_RUNNER_NAME should be codebuild-EmbeddedLinuxCodebuildProjeNAME with prefix codebuild-. See example here.

Example stack name: EmbeddedLinuxCodeBuildProject

Useful NPM and CDK commands

• npm run build compile typescript to js
• npm run watch watch for changes and compile
• npm run test perform the jest unit tests
• cdk deploy deploy this stack to your default AWS account/region
• cdk diff compare deployed stack with current state
• cdk synth emits the synthesized CloudFormation template

Project Specific:

• npm run format runs prettier and eslint on the repository
• npm run zip-data bundles the files for creating build host containers
• npm run check checks for lint and format issues
• npm run docs to generate documentation

Security

See SECURITY for more information.

Contributing

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.