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

mike · October 19, 2022, 4:14pm

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:

Create a “standalone repo” using a Zephyr west manifest file
Use west init to check out the standalone repo from Github
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

manifest:
  projects:
    - name: golioth
      path: modules/lib/golioth
      revision: v0.3.1
      url: https://github.com/golioth/golioth-zephyr-sdk
      west-commands: scripts/west-commands.yml
      import:
        file: west-zephyr.yml
        path-prefix: deps
  self:
    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

my-zephyr-project
├── 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.