Getting started on macOS

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

Prerequisites

• A machine running macOS
• Homebrew

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.

Procedure

1. Clone the automotive sample-images repository into your current directory:

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

2. Install Podman 5:

   $ brew install podman
   

3. Install QEMU:

   $ brew install qemu
   

4. Download Automotive Image Runner (air), a tool that you can use to quickly boot AutoSD images with QEMU:

   $ curl -o air \
   "https://gitlab.com/CentOS/automotive/src/automotive-image-builder/-/raw/main/bin/air"
   

5. Make the air tool executable:

   $ chmod +x air
   

6. Initialize a Podman machine with rootful support for image builds:

   $ podman machine init --rootful
   

7. Start the Podman machine:

   $ podman machine start
   

8. Get the auto-image-builder.sh script:

   $ curl -O "https://gitlab.com/CentOS/automotive/src/automotive-image-builder/-/raw/main/auto-image-builder.sh?ref_type=heads"
   

9. Make the auto-image-builder.sh script executable:

   $ chmod +x auto-image-builder.sh
   

10. Build a disk image with the auto-image-builder.sh:

    $ ./auto-image-builder.sh -d build \
        --target qemu \
        sample-images/images/simple-developer.aib.yml \
        my-image.qcow2
    

11. Launch your new AutoSD image:

    $ ./air --nographics my-image.qcow2
    

    Login credentials:

    • Username: root
    • Password: password

    Note

    Setting the PasswordAuthentication option to yes in sshd_config in the auth: section of your Automotive Image Builder manifest enables ssh access. With ssh enabled, you can access the VM by running ssh -p 2222 -o "UserKnownHostsFile=/dev/null" guest@localhost.

The simple-developer.aib.yml Automotive Image Builder manifest builds a developer image with a number of utilities installed for development purposes. For more information about the Automotive Image Builder manifests, see Introducing Automotive Image Builder. For more information about creating a custom manifest, see Building an image from a custom manifest.

The auto-image-builder.sh script can be run with 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 auto-image-builder.sh 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 autosd10-sig if no option is specified. Run auto-image-builder.sh list-distro to view the list of available options. You can also extend this list with your own custom distribution. For more information, see distributions.

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 CPU architecture images. To explore the sample images, see the nightly sample images.

This following example build uses the nightly aarch64 developer image. For this example to work, you must be running macOS on a machine with an Apple Silicon ARM processor. If you are running macOS on a machine with x86_64 processor, you can adapt the procedure by downloading the developer image built for the X86_64 architecture instead.

Procedure

1. Install QEMU and XZ Utils:

   $ brew install qemu xz
   

2. Go to the sample-images directory where you cloned the GitLab sample-images repository.

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

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

   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 AutoSD sample images.

4. Download the image:

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

5. Uncompress the compressed .xz image file:

   $ xz -d autosd10-developer-regular-aarch64.qcow2.xz
   

6. From the sample-images directory, launch a VM from the image with the air tool from the automotive-image-builder repository:

   $ ./air --nographics <path>/autosd10-developer-regular-aarch64.qcow2
   

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

   Note

   Setting the PasswordAuthentication option to yes in sshd_config in the auth: section of your Automotive Image Builder manifest enables ssh access. With ssh enabled, you can access the VM by running ssh -p 2222 -o "UserKnownHostsFile=/dev/null" guest@localhost.

Building customized AutoSD images in a QEMU VM

Repeat the procedure in 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 Automotive Image Builder to create customized AutoSD system images using your custom manifest .aib.yml file.

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

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

Prerequisites

• The latest nightly auto-osbuild-qemu-autosd10-developer-ostree-aarch64-<version>.qcow2 image. If you have not done so already, follow the procedure in Booting prebuilt AutoSD images in a QEMU VM, to download the latest nightly developer image.

Procedure

1. Extend the virtual disk of your .qcow2 development image to ensure that your AutoSD image has enough space to facilitate your custom development work.

   1. On the macOS host, resize your development image. In this example, set the disk size to 100G, which will enable you to resize the main disk partition to 100 gigabytes in the VM:

      $ qemu-img resize autosd10-developer-regular-aarch64.qcow2 100G
      

   2. Launch your virtual AutoSD development environment from the sample-images directory:

      $ ./air --nographics autosd10-developer-regular-aarch64.qcow2
      

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

      Note

      Setting the PasswordAuthentication option to yes in sshd_config in the auth: section of your Automotive Image Builder manifest enables ssh access. With ssh enabled, you can access the VM by running ssh -p 2222 -o "UserKnownHostsFile=/dev/null" guest@localhost.

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

   $ su -
   

3. Install the automotive-image-builder and thee2fsprogs and parted file system utilities so that you can expand the file system:

   # dnf -y install automotive-image-builder parted e2fsprogs
   

   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. If prompted to fix the GPT to use all available space, enter fix.

   4. If prompted for a partition number, enter 3, and when prompted to continue, enter yes.

   5. At the End? prompt, enter 102400, which will extend the partition size to 100GB.

   6. Exit the parted tool:

      (parted) quit
      

   7. Resize the file system:

      # resize2fs /dev/vda3
      

   8. Confirm that the /dev/vda3 partition has been resized to around 100GB:

      # df -h /dev/vda3
      

4. Install Automotive Image Builder by following these steps:

   1. Install dnf plugin tools so that you can enable a copr repository:

      # dnf install 'dnf-command(copr)'
      

   2. Enable the automotive-image-builder and osbuild-auto copr repository:

      # dnf copr enable @centos-automotive-sig/automotive-image-builder
      # dnf copr enable @centos-automotive-sig/osbuild-auto
      

   3. Install the automotive-image-builder and osbuild-auto packages:

      # dnf install automotive-image-builder osbuild-auto
      

5. Clone the AutoSD sample-images GitLab repository in your devlopment VM:

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

6. In your development VM in the sample-images directory you just cloned, create a custom Automotive Image Builder manifest file that you can configure according to your requirements:

   # vim my-manifest.aib.yml
   

   Note

   The Automotive SIG provides several sample .aib.yml manifest files in sample-images/images/ that you can reference or copy. For more information about available sample images, see AutoSD sample images. To view an example customized manifest, see Sample customized Automotive Image Builder manifest. For more details about how to build and customize images, see Building an image from a custom manifest and Embedding RPM packages from local storage into the AutoSD image.

7. If you have not done so already, add the following code to the auth: section of your custom my-manifest.aib.yml file to allow ssh password authentication and root access to the running VM:

       PasswordAuthentication: true
       PermitRootLogin: true
   

8. Build a disk image from your custom my-manifest.aib.yml:

   $ aib-dev build \
       --target qemu \
       my-manifest.aib.yml \
       my-image.qcow2
   

   Note

   For more information about the build options that Automotive Image Builder supports, see Automotive Image Builder tool.

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

9. With the VM still running, open a new terminal window on your macOS host machine, change to the sample-images repository directory, and import your custom my-image.qcow2 OS image file from the VM to the host:

   $ scp -P 2222 -o "UserKnownHostsFile=/dev/null" root@localhost:/root/sample-images/my-image.qcow2 .
   

10. On the macOS host, while still in the sample-images directory, launch a VM from your new image:

    $ air --nographics my-image.qcow2
    

For more information about how to build your own customized AutoSD images, see Building an image from a custom manifest