How do I lock my project to a specific Golioth version?

We always recommend using a west manifest to lock your project to a specific version of Golioth. Rather than always tracking the main branch, choosing a specific version of the SDK ensures that you make the decisions on when to update Golioth/Zephyr/Module versions built into your project.

This approach creates a subfolder where a Zephyr workspace dedicated to this project will be place.

Objectives of this guide:

  1. Create a “standalone repo” using a Zephyr west manifest file
  2. Use west init to check out the standalone repo from Github
  3. Understand the directory structure of this standalone repo

Creating a standalone repository in Zephyr

1. Start with a Zephyr project

This can be your existing project or something like the Hello sample from the Golioth repository.

2. Add a west manifest file

    - name: golioth
      path: modules/lib/golioth
      revision: v0.3.1
      west-commands: scripts/west-commands.yml
        file: west-zephyr.yml
        path-prefix: deps
    path: app

Add this manifest file to the root of your application and commit it to your git repository.

Note that this example locks the project to Golioth Zephyr SDK v0.3.1 but any tag/branch/hash from the git repository can be used as the “revision” value.

This manifest file also imports the west-zephyr.yml manifest from the Golioth repo. If you are using a Nordic part, change this to west-ncs.yml.

Use west init to clone the repository

This is an important thing to understand: you should not use git clone to check out a “standalone” Zephyr repo. Instead, the west meta tool will do the cloning, placing everything where it needs to go.

Here are the verbose commands I use to check out a new standalone repository, including setting up and using the Python virtual environment:

#Create dir, install and activate virtual environment
mkdir my-zephyr-project
python -m venv my-zephyr-project/.venv
source my-zephyr-project/.venv/bin/activate

#Install wheel and west
pip install wheel
pip install west

#Use west to clone and initialize the repo
west init -m [email protected]:szczys/my-zephyr-project.git my-zephyr-project

#Use west to set up the Zephyr workspace (clone modules, dependencies)
cd my-zephyr-project/
west update
west zephyr-export
pip install -r deps/zephyr/scripts/requirements.txt

Remember in that each new terminal session where you want to use this standalone repo you need to activate the Python virtual environment to take advantage of the packages that were installed in the .venv folder:

#Activate Python virtual environment
cd my-zephyr-project
source .venv/bin/activate

Directory structure of the standalone repo

├── app
│   ├── boards
│   ├── CMakeLists.txt
│   ├── Kconfig
│   ├── prj.conf
│   ├── README.rst
│   ├── src
│   └── west.yml
└── deps
    ├── bootloader
    ├── modules
    ├── tools
    └── zephyr

After using west init, your repository will be located in the app subfolder. The Zephyr repository and modules will be located in the deps folder. The app folder is where you should do your development, run the west build commands, and perform the git commit operations to track your changes.

Further reading

Your west manifest can optionally include or exclude packages. For instance, take a look at the west manifest for our magtag-demo repository. It only allows the packages necessary to build for the esp32 since this is the chip the project is based upon.

The Zephyr Docs have in-depth information on the west manifest and are worth reading.