Adding your own code

To maintain an application that uses Bridle, you should use the same tools that TiaC Systems members use to develop it. This section describes suggested user workflows to develop and maintain an application based on Bridle.

See Bridle code base for detailed information on how the Bridle repositories are organized.

User workflows

The following workflows present different ways of adding your own code to Bridle. They describe the actual practicalities of developing an application that is based on Bridle from a version control and maintenance point of view.

Which user workflow to choose depends on the type of application, the timeframe to develop it, and the need to update Bridle version used.

All workflows are described under the following basic assumptions:

  • One or more applications are to be developed using Bridle.

  • Additional board definitions might be required by the user.

  • Additional libraries might be required by the user.

  • The term application refers to the application code and any board definitions and libraries it requires.

  • The application(s) will require updates of the Bridle revision.

Workflow 1: Eschew Git and west

Attention

This method of operation should be used only in the case of absolute necessity and should be avoided. Git and west are very powerful tools and cover almost every required workflow, including regulatory compliance with required traceability.

If you have your own version control tools, you might want to simply not use Git or west at all, and instead rely on your own toolset. In such case, you must obtain a copy of Bridle on your file system and then manage the source code of both the SDK and your application yourself.

Since no downloadable packages of Bridle are currently available, the simplest path to obtain the source code is to follow the instructions in the corresponding section of the documentation. This requires you to install Git and west, but you can then ignore them from that point onwards. If you need to update the copy of Bridle you are working with, you can obtain the source code again, or, if you have kept the original set of repositories, update it instead. Once you have obtained a copy of the Bridle source code, which is self-contained in a single folder, you can then proceed to manage that code in any way you see fit.

Unless you take some additional steps, west itself must still be installed in order to build applications.

Workflow 2: Out-of-tree application repository

Another approach to maintaining your application is to completely decouple it from the Bridle repositories and instead host it wherever you prefer - in Git, another version control system, or simply on your hard drive. This is typically also known as “out-of-tree” application, meaning that the application, board definitions, and any other libraries are actually outside any of the repositories provided by TiaC Systems and can be placed anywhere at all. As long as you do not need to make any changes to any of the repositories of Bridle, you can use the procedures to get the source code and later update it, and manage your application separately, inside or outside the top folder of Bridle.

If you choose to have your application outside of the folder hierarchy of Bridle, the build system will find the location of the SDK through the ZEPHYR_BASE environment variable, which is set either through a script or manually in an IDE. More information about application development and the Bridle build and configuration system can be found in the Build and configuration system documentation section.

The drawback with this approach is that any changes you make to the set of Bridle repositories are not directly trackable using Git, since you do not have any of the Bridle repositories forked. If you are tracking the master branch of the Bridle, you can instead send the changes you require to the official repositories as Pull Requests, so that they are incorporated into the codebase.

Workflow 3: Application in a fork of tiac-bridle

Forking the tiac-bridle repository and adding the application to it is another valid option to develop and maintain your application. This approach also allows you to fork additional Bridle repositories and point to those. This can be useful if you have to make changes to those repositories beyond adding your own application to the manifest repository.

In order to use this approach, you first need to get the source code, and then fork the tiac-bridle repository. Once you have your own fork, you can start adding your application to your fork’s tree and push it to your own Git server. Every time you want to update the revision of the Bridle that you want to use as a basis for your application, you must follow the instructions to update on your own fork of tiac-bridle.

If you have changes in additional repositories beyond tiac-bridle itself, you can point to your own forks of those in the west.yml included in your fork.

Workflow 4: Application as the manifest repository

An additional possibility is to take advantage of west to manage your own set of repositories. This workflow is particularly beneficial if your application is split among multiple repositories or, just like in the previous workflow, if you want to make changes to one or more Bridle repositories, since it allows you to define the full set of repositories yourself.

In order to implement this approach you first need to create a manifest repository of your own, which just means a repository that contains a west.yml manifest file in its root. Next you must populate the manifest file with the list of repositories and their revisions.

In general, the easiest thing to do is to import the west.yml into tiac-bridle, using west’s manifest imports feature. This is demonstrated by the following code:

# Example application-specific west.yml, using manifest imports.
manifest:
  remotes:
    - name: tiacsys
      url-base: https://github.com/tiacsys
  projects:
    - name: bridle
      repo-path: bridle
      remote: tiacsys
      revision: v0.1.5
      import: true
  self:
    path: application

Importing west.yml also results in the addition of all the Bridle projects, including those imported from Zephyr, into your workspace.

Then, make the following changes:

  • Point the entries of any Bridle repositories that you have forked to your fork and fork revision, by adding them to the projects list using a new remote.

  • Add any entries for repositories that you need that are not part of Bridle.

For example:

# Example your-application/west.yml, using manifest imports, with
# an BRIDLE fork and a separate module
manifest:
  remotes:
    - name: tiacsys
      url-base: https://github.com/tiacsys
    - name: your-remote
      url-base: https://github.com/your-name
  projects:
    - name: bridle
      remote: tiacsys
      revision: v0.1.5
      import: true
    # Example for how to override a repository in the BRIDLE with your own:
    - name: mcuboot
      remote: your-remote
      revision: your-mcuboot-fork-SHA-or-branch
    # Example for how to add a repository not in BRIDLE:
    - name: your-custom-library
      remote: your-remote
      revision: your-library-SHA-or-branch
  self:
    path: application

The variable values starting with your- in the above code block are just examples and you can replace them as needed. The above example includes a fork of the mcuboot project, but you can fork any project in bridle/west.yml.

Once you have your new manifest repository hosted online, you can use it with west just like you use the tiac-bridle repository when getting and later updating the source code. You just need to replace tiac-bridle and bridle with the repository name and path you have chosen for your manifest repository (your-name/your-application and your-ncs-fork, respectively), as shown in the following code:

west init -m https://github.com/your-name/your-application your-tiacsys-fork
cd your-tiacsys-fork
west update

After that, to modify the Bridle version associated with your app, change the revision value in the manifest file to the tiac-bridle Git tag, SHA, or the branch you want to use, save the file, and run west update. See Multiple Repository Model for more details.