Building AGL Development Enviornment on Mac: 1. Build Yocto using Docker in 2025

AGL Yocto Docker
Go Go
| November 13, 2025

Step-by-step: use Docker on macOS to create a persistent workdir volume, expose via Samba, and run the poky/poky-like container to build Yocto (2025 notes).

Overview

This post documents how to set up a Yocto build environment on macOS using Docker (updated notes for 2025). The approach uses a Docker volume for the work directory, a small Samba container to expose the volume to Finder, and a Yocto/poky container for interactive build work.

Follow the commands exactly in a macOS terminal. Where sudo is required you’ll be prompted for your password.

1. Install and run Docker for Mac

Install Docker Desktop for Mac and ensure it runs. Follow the official Docker documentation:

Once Docker Desktop is running, open a terminal.

2. Start a terminal

You can open the default macOS Terminal by pressing Command–Space and typing Terminal.

3. Create the volume

Create a Docker volume named myvolume. This will hold the Yocto workspace so it persists across containers.

Terminal window
docker volume create --name myvolume

Set ownership inside the volume to uid 1000:1000 so container users match a common Linux uid/gid (some images expect non-root users):

Terminal window
docker run -it --rm -v myvolume:/workdir busybox chown -R 1000:1000 /workdir

4. Create and run a Samba container

Create a lightweight Samba container that mounts the myvolume volume and exposes it on port 445 so you can access it from Finder.

Terminal window
docker create -t -p 445:445 --name samba -v myvolume:/workdir crops/samba

Start the Samba container:

Terminal window
docker start samba

5. Create an alias for 127.0.0.1

macOS will not let you directly connect to a locally-hosted Samba share at 127.0.0.1, so create an alias address on the loopback interface (127.0.0.2) and use that to connect.

Terminal window
sudo ifconfig lo0 127.0.0.2 alias up

Tip: combine starting samba and creating the alias in one command for convenience:

Terminal window
docker start samba && sudo ifconfig lo0 127.0.0.2 alias up

Note: The alias is ephemeral and will be removed on reboot. If you need it persistently, consider adding an appropriate boot-time script (e.g., a LaunchDaemon), or re-run the alias command when needed.

6. Open the workdir in Finder

Open Finder, press Command–K (Connect to Server), and enter:

smb://127.0.0.2/workdir

Select “Guest” login and click “Connect”. You should now see the workdir contents in Finder. This makes it easy to edit files from your macOS editor while builds run inside containers.

7. Start a container to do work

Now run your Yocto/poky container and mount the same myvolume volume at /workdir. The container can be started with the workdir set as the starting directory so you land in the shared workspace immediately.

For generic Yocto/poky work:

Terminal window
docker run --rm -it -v myvolume:/workdir crops/poky --workdir=/workdir

For AGL development (recommended for this series):

Terminal window
docker run --rm -it -v myvolume:/workdir dnangellight/agl-poky-dev:latest --workdir=/workdir

Notes:

  • The --workdir=/workdir flag causes the container to start in that directory. The container will honor the uid/gid mapping previously set on the volume (uid 1000 in our chown step).
  • The dnangellight/agl-poky-dev:latest container comes pre-configured with all AGL development tools including git, curl, python3, and the repo tool.

When successful you should see a prompt like:

agluser@3bbac563cacd:/workdir$

(or pokyuser@... if using the crops/poky container)

From here you can fetch layers, configure builds, and run bitbake inside the container. Files edited in Finder will be visible immediately inside the container because they share the same volume.

8. Use Git to clone Poky

Once inside the container, you need to get a copy of the Poky repository. Use the following commands to clone it:

Terminal window
git clone git://git.yoctoproject.org/poky

You’ll see output like:

Cloning into 'poky'...
remote: Counting objects: 432160, done.
remote: Compressing objects: 100% (102056/102056), done.
remote: Total 432160 (delta 323116), reused 432037 (delta 323000)
Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
Resolving deltas: 100% (323116/323116), done.
Checking connectivity... done.

Go to the Yocto Project Releases wiki page and choose a release codename corresponding to either the latest stable release or a Long Term Support release (e.g., walnascar, dunfell, gatesgarth).

Move to the poky directory and check existing branches:

Terminal window
cd poky
git branch -a

You’ll see output like:

remotes/origin/HEAD -> origin/master
remotes/origin/dunfell
remotes/origin/dunfell-next
remotes/origin/gatesgarth
remotes/origin/gatesgarth-next
remotes/origin/master
remotes/origin/master-next

For this example, check out the walnascar branch based on the Walnascar release:

Terminal window
git checkout -t origin/walnascar -b my-walnascar

Output:

Branch 'my-walnascar' set up to track remote branch 'walnascar' from 'origin'.
Switched to a new branch 'my-walnascar'

This creates a local branch named my-walnascar. The files in that branch exactly match the repository’s files in the walnascar release branch.

Note: You can regularly sync your local files with the release branch by running:

Terminal window
git pull

9. Initialize the build environment

From within the poky directory, run the oe-init-build-env environment setup script to define Yocto Project’s build environment:

Terminal window
cd poky
source oe-init-build-env

You’ll see output like:

You had no conf/local.conf file. This configuration file has therefore been
created for you with some default values. You may wish to edit it to, for
example, select a different MACHINE (target hardware). See conf/local.conf
for more information as common configuration options are commented.


You had no conf/bblayers.conf file. This configuration file has therefore
been created for you with some default values. To add additional metadata
layers into your configuration please add entries to conf/bblayers.conf.


The Yocto Project has extensive documentation about OE including a reference
manual which can be found at:
    https://docs.yoctoproject.org


For more information about OpenEmbedded see their website:
    https://www.openembedded.org/


### Shell environment set up for builds. ###


You can now run 'bitbake <target>'


Common targets are:
    core-image-minimal
    core-image-full-cmdline
    core-image-sato
    core-image-weston
    meta-toolchain
    meta-ide-support


You can also run generated QEMU images with a command like 'runqemu qemux86-64'


Other commonly useful commands are:
 - 'devtool' and 'recipetool' handle common recipe tasks
 - 'bitbake-layers' handles common layer tasks
 - 'oe-pkgdata-util' handles common target package tasks

Note: If you are working behind a firewall and your build host is not set up for proxies, you could encounter problems with the build process when fetching source code (e.g., fetcher failures or Git failures). Consult your local network infrastructure resources for proxy settings, or check the Yocto Project Wiki page on Working Behind a Network Proxy.