Getting started on MacOS

Set up your development environment with the prerequisite tools and repositories you need to quickly start building AutoSD images in either a preconfigured container or a virtual machine (VM).

Prerequisites

• A machine running MacOS
• Homebrew
• A local clone of the AutoSD sample-images repository with the automotive-image-builder submodule

Quick start: Building AutoSD images

You can use the preconfigured AutoSD development container as a lightweight base development environment if you want to build an AutoSD image without launching and configuring a development VM.

Prerequisites

• A local clone of the AutoSD sample-images repository

Procedure

1. Install Podman 5:

   brew install podman
   

2. Initialize a Podman machine with rootful support for OSBuild:

   podman machine init --rootful
   

3. Start the Podman machine:

   podman machine start
   

4. Navigate to the sample-images directory:

   cd sample-images
   

5. Build an image with the auto-image-builder.sh script:

   sudo ./auto-image-builder.sh build --target qemu --export qcow2 images/developer.mpp.yml my-image.qcow2
   

   In this example, include the images/developer.mpp.yml OSBuild manifest file to build a developer image. The developer image has a number of utilities installed for development purposes. You can view the available sample manifests in sample-images/images, and you can create your own manifest that contains your custom configurations. For more information about the sample manifests, see Sample OSBuild manifests. For more information about creating a custom manifest, see Deploying software on AutoSD.

   The build command takes a variety of inputs:

   • Use --target to set the target environment. The default is qemu. Use qemu to build an image that you can launch in a QEMU virtual machine. Run --list-targets to view the list of available options.
   • Use --distro to define the package repository that you want to use for the image build. The default is CentOS Stream 9 (cs9). Run --list-dist to view the list of available options. You can also extend this list with your own custom distribution. For more information, see distributions.
   • Use --export to set the export file format. Run --list-exports to view the list of available options.
   • Use --mode to set the type of OS image. This can be package, to build a package-based operating system image, or image to build an OSTree image. For development and testing purposes, use package. For production, use image.

   You can also include command-line overrides for certain parameters. For syntax and a full list of overrides, see Overriding variables from the command line.

Quick start: Booting prebuilt AutoSD images in a QEMU VM

A virtualized AutoSD development environment is similar to a AutoSD production environment. The virtualized platform is useful for building and testing applications intended to run on a AutoSD system or to build new AutoSD images that you can flash onto automotive hardware or use on other systems.

Download and uncompress a prebuilt AutoSD operating system (OS) image, and then launch a VM from the image. This VM is your development environment, where you can customize and build your own AutoSD images.

All prebuilt AutoSD images can be found in the nightly repo. The repo features both x86_64 and aarch64 architecture images. To explore the sample images, see sample images. In this example, use the aarch64 developer image for Apple silicon. The developer image has extra storage compared to other images.

Procedure

1. Install QEMU and XZ Utils:

   brew install qemu xz
   

2. Identify the name of the latest nightly image for your host architecture, and store the value in a variable called AUTOSD_IMAGE_NAME.

   Note

   The Automotive SIG uploads images every day using unique build IDs, which causes the name of the image to change frequently. For more information about available nightly images, their purposes, and their naming conventions, see Sample OS images.

   $ export AUTOSD_IMAGE_NAME="$(curl https://autosd.sig.centos.org/AutoSD-9/nightly/sample-images/ | \
   grep -oE 'auto-osbuild-qemu-autosd9-developer-regular-aarch64-([0-9]+)\.([A-Za-z0-9]+)\.qcow2\.xz' | \
   head -n 1)"
   

3. Download the image:

   curl -o autosd9-developer-regular-aarch64.qcow2.xz https://autosd.sig.centos.org/AutoSD-9/nightly/sample-images/$AUTOSD_IMAGE_NAME
   

4. Uncompress the compressed .xz image file:

   xz -d autosd9-developer-regular-aarch64.qcow2.xz
   

5. Launch a VM from the image with the automotive-image-runner script from the the automotive-image-builder directory of your local clone of the AutoSD sample-images repository:

   cd sample-images/automotive-image-builder
   ./automotive-image-runner <path>/autosd9-developer-regular-aarch64.qcow2
   

6. Log in as the root user with the default password, password.

   Note

   To enable ssh access, you must set PasswordAuthentication yes in /etc/ssh/sshd_config. Then you can access the machine with ssh -p 2222 -o "UserKnownHostsFile=/dev/null" guest@localhost.

Quick start: Building customized AutoSD images in a QEMU VM

Repeat the procedure in Quick start: Booting prebuilt AutoSD images in a QEMU VM, to download and run the latest nightly developer image, which has extra storage compared to the other sample images. Then, expand the disk size, so you can use the automotive-image-builder tool to create customized system images using your custom manifest .mpp.yml file.

For more information about the preconfigured manifest files the Automotive SIG provides as starter examples you can modify, see the Sample OSBuild manifests.

For more in-depth information about how to package your applications and embed them in a customized manifest you can then use to generate your customized OS image, see Packaging applications with RPM and Embedding RPM packages in the AutoSD image sections.

Prerequisites

• The latest nightly autosd9-dev-reg-aarch64.qcow2 image

Procedure

1. Extend the virtual disk of your .qcow2 development image, so that you have enough space to build your custom AutoSD images and facilitate your development work.

   1. On the host, resize your development image. In this example, set the disk size to 30G, which is 30GiB:

      qemu-img resize autosd9-dev-reg-aarch64.qcow2 30G
      

   2. Launch your virtual AutoSD development environment:

      cd sample-images/automotive-image-builder
      ./automotive-image-runner autosd9-dev-reg-aarch64.qcow2
      

   3. Log in with the guest user and the default password password.

      Note

      To enable ssh access, you must set PasswordAuthentication yes in /etc/ssh/sshd_config. Then you can access the machine with ssh -p 2222 -o "UserKnownHostsFile=/dev/null" guest@localhost.

2. Change to the root user. The root user password is also password:

   su -
   

3. Install the parted partition management tool to extend the file system:

   dnf -y install parted
   

   1. Run parted to extend the size of /dev/vda:

      parted /dev/vda
      

   2. Resize the /dev/vda3 partition to fill the space available to that partition:

      (parted) resizepart 3 100%
      

   3. Exit the parted tool:

      (parted) quit
      

   4. Enlarge the file system:

      resize2fs /dev/vda3
      

4. Clone the AutoSD sample-images repository in your development VM.

   git clone --recursive https://gitlab.com/CentOS/automotive/sample-images.git
   

5. In your development VM, create a custom OSBuild manifest file that you can configure according to your requirements:

   vim my-manifest.mpp.yml
   

   Note

   The Automotive SIG provides several sample manifest files in sample-images/images/ you can reference. For more information about available sample images, see Sample OS images. To view an example customized manifest, see Sample customized OSBuild manifest. For more details about how to build and customize images, see Deploying software on AutoSD and Embedding RPM packages in the AutoSD image.

6. Build the OS image from your custom my-manifest.mpp.yml. In this example, build a qcow2 format for the qemu target so that you can launch your image in a VM:

   cd sample-images
   sudo ./auto-image-builder.sh build --target qemu --export qcow2 my-manifest.mpp.yml my-image.qcow2
   

   Note

   For more information about the export file types automotive-image-builder supports, see Export formats in the automotive-image-builder options section.

   For more information about image naming conventions, see AutoSD sample images.

7. Exit the VM and export the image file to the host:

   scp -P 2222 "UserKnownHostsFile=/dev/null" guest@localhost:/home/guest/sample-images/my-image.qcow2 .
   

8. On the host, launch a VM from your new image:

   ./automotive-image-runner my-image.qcow2
   

For more information about how to build your own customized AutoSD images, see Building and running your customized OS image.