Support > FAQ > GitHub Repository Structure & Versioning
Homepage | FAQ
FreeRTOS FAQ - GitHub Repository Structure & Versioning
This is a subsection of the full FAQ
How are FreeRTOS Git repositories structured?
How are FreeRTOS libraries versioned?
Which library packages are available?
How do I obtain and use individual FreeRTOS libraries?
How do I obtain a FreeRTOS distribution package?
This is a subsection of the full FAQ
How are FreeRTOS Git repositories structured?
There are two types of repositories, single library repositories and package repositories. Each single library
repository contains the source code for one library without any build projects or examples. Package repositories
contain multiple libraries, and may contain pre-configured projects that demonstrate the library’s use.
While package repositories contain multiple libraries, they do not contain copies of those libraries. Instead,
package repositories reference the libraries they contain as
git sub-modules. Using sub-modules ensures
there is a single source of truth for each individual library.
The individual library git repositories are split between two GitHub organisations. Repositories containing
FreeRTOS specific libraries (such as FreeRTOS-Plus-TCP) or generic libraries (such as coreMQTT, which is cloud
agnostic because it works with any MQTT broker) are in the FreeRTOS
GitHub organisation. Repositories containing AWS IoT specific libraries (such as the AWS IoT over-the-air
update client) are in the AWS GitHub organisation.
The following diagram demonstrates the structure.
GitHub Repository Structure - click to enlarge
How are FreeRTOS libraries versioned?
Individual libraries use x.y.z style version numbers, similar to semantic
versioning. x is the major version number, y the minor version number, and (from 2022) z is a patch number.
Prior to 2022, z was a point release number, meaning patches to the first LTS libraries required
a separate patch number of the form "x.y.z LTS Patch 2".
The LTS version of a FreeRTOS library will reserve the z in x.y.z for LTS patches. For example, if 3.1.0 is the LTS
version of a FreeRTOS library, 3.1.1 will be a patch to the LTS version. This implies that a non-LTS point release of the library from
the 3.1.z release commit will have to increment the minor (i.e y) number rather than the z number. This is
so that patches to the LTS version can extended.
The reservation of z applies only to LTS versions of a library. Non-LTS versions of a library will increment z for point releases. For
example, in subsequent releases from mainline, a future version of a FreeRTOS library, say 3.3.0, can make a point release of 3.3.1
while 3.1.0 continues to be the LTS version.
Library packages use yyyymm.x style date stamp version numbers. yyyy is the year, mm the month of the release,
and x is a sequential patch number. The individual libraries contained in a package are whatever the latest version of
that library was on that date (or, in the case of the LTS package, the latest patch version of the LTS libraries originally released as an LTS version on that date).
Which library packages are available?
There are four library packages.
-
Primary FreeRTOS distribution (from the FreeRTOS GitHub organization):
This contains many pre-configured projects that demonstrate the FreeRTOS kernel running on different processors
and using different compilers, as well as projects that demonstrate other FreeRTOS libraries (such as
FreeRTOS-Plus-TCP) running in emulated environments.
-
Featured FreeRTOS IoT reference integrations (from the FreeRTOS GitHub organization):
Featured FreeRTOS IoT integrations are pre-configured projects that demonstrate best practices to make IoT device software more secure and robust. These FreeRTOS IoT integrations are designed for improved security using a combination of FreeRTOS software and a partner-provided board with hardware security features.
-
AWS IoT Embedded C SDK for devices (from the AWS GitHub organization):
This contains many pre-configured projects that demonstrate the integration of FreeRTOS and AWS libraries running on a POSIX operating system instead of FreeRTOS.
-
LTS versions of FreeRTOS libraries (from the FreeRTOS GitHub organization):
This is for reference and convenience only. It contains just the
Long Term Support (LTS) versions of the FreeRTOS
libraries, with no example projects.
How do I obtain and use individual FreeRTOS libraries?
The recommended way to use individual libraries in your application is to sub-module them directly from GitHub into your application
project. Alternatively, you can copy an individual library into your application by downloading a zip file of the
library from the GitHub repository's Releases area. The following table contains links to individual libraries. The package downloads contain examples.
How do I obtain a FreeRTOS distribution package?
Here are instructions for each package. Note, if using git to obtain a library package then additionally follow the repository cloning instructions in the package’s readme.md file to ensure you also initialize and sync sub-module references:
-
Primary FreeRTOS distribution:
Most people use the download button on the FreeRTOS.org website
to obtain a zip file. The package distribution is also available from GitHub as either a
git repository or
zip file.
-
Featured FreeRTOS IoT integrations:
Each featured integration is distributed in a separate repository under FreeRTOS github organization with the "iot-reference-targetplatform" name format. Check for the list of the latest projects from the Featured FreeRTOS IoT Integration pages.
-
AWS IoT Embedded C SDK for devices:
This package is available from GitHub as either a
git repository or
zip file.
-
LTS versions of FreeRTOS libraries:
Similar to the primary FreeRTOS distribution, most people use the
download button on the FreeRTOS.org website to obtain a zip
file. The distribution is also available from GitHub as either a
git repository or
zip file.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.