Adding your own code¶
To maintain an application that uses the nRF Connect SDK, you should use the same tools that Nordic Semiconductor employs to develop it. This section describes suggested user workflows to develop and maintain an application based on the nRF Connect SDK.
See nRF Connect SDK code base for detailed information on how the nRF Connect SDK repositories are organized.
User workflows¶
The following workflows present different ways of adding your own code to the nRF Connect SDK. They describe the actual practicalities of developing an application that is based on the nRF Connect SDK 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 the nRF Connect SDK version used.
All workflows are described under the following basic assumptions:
One or more applications are to be developed using the nRF Connect SDK.
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 nRF Connect SDK revision.
Workflow 1: Eschew Git and west¶
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 the nRF Connect SDK on your file system and then manage the source code of both the SDK and your application yourself.
Since no downloadable packages of the nRF Connect SDK 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 the nRF Connect SDK 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 nRF Connect SDK 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 nRF Connect SDK 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 the nRF Connect SDK and can be placed anywhere at all. As long as you do not need to make any changes to any of the repositories of the nRF Connect SDK, 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 the nRF Connect SDK.
If you choose to have your application outside of the folder hierarchy of the nRF Connect SDK, 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 nRF Connect SDK 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 nRF Connect SDK repositories are not directly trackable using Git, since you do not have any of the nRF Connect SDK repositories forked. If you are tracking the master branch of the nRF Connect SDK, 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 sdk-nrf¶
Forking the sdk-nrf 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 nRF Connect SDK 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 sdk-nrf 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 nRF Connect SDK that you want to use as a basis for your application, you must follow the instructions to update on your own fork of sdk-nrf.
If you have changes in additional repositories beyond sdk-nrf 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 nRF Connect SDK 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 sdk-nrf, using west’s manifest imports feature.
This is demonstrated by the following code:
# Example application-specific west.yml, using manifest imports.
manifest:
remotes:
- name: ncs
url-base: https://github.com/nrfconnect
projects:
- name: nrf
repo-path: sdk-nrf
remote: ncs
revision: v1.6.1
import: true
self:
path: application
Importing west.yml also results in the addition of all the nRF Connect SDK projects, including those imported from Zephyr, into your workspace.
Then, make the following changes:
Point the entries of any nRF Connect SDK repositories that you have forked to your fork and fork revision, by adding them to the
projectslist using a new remote.Add any entries for repositories that you need that are not part of the nRF Connect SDK.
For example:
# Example your-application/west.yml, using manifest imports, with
# an nRF Connect SDK fork and a separate module
manifest:
remotes:
- name: ncs
url-base: https://github.com/nrfconnect
- name: your-remote
url-base: https://github.com/your-name
projects:
- name: nrf
remote: ncs
revision: v1.6.1
import: true
# Example for how to override a repository in the nRF Connect SDK with your own:
- name: mcuboot
remote: your-remote
revision: your-mcuboot-fork-SHA-or-branch
# Example for how to add a repository not in nRF Connect SDK:
- 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 nrf/west.yml.
Once you have your new manifest repository hosted online, you can use it with west just like you use the sdk-nrf repository when getting and later updating the source code.
You just need to replace sdk-nrf and nrf 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-ncs-fork cd your-ncs-fork west update
After that, to modify the nRF Connect SDK version associated with your app, change the revision value in the manifest file to the sdk-nrf Git tag, SHA, or the branch you want to use, save the file, and run west update.
See Basics for more details.