1[](https://github.com/FreeRTOS/FreeRTOS-Kernel/actions/workflows/unit-tests.yml?query=branch%3Amain+event%3Apush+workflow%3A%22CMock+Unit+Tests%22++) 2[](https://codecov.io/gh/FreeRTOS/FreeRTOS-Kernel) 3 4## Getting started 5 6This repository contains FreeRTOS kernel source/header files and kernel 7ports only. This repository is referenced as a submodule in 8[FreeRTOS/FreeRTOS](https://github.com/FreeRTOS/FreeRTOS) 9repository, which contains pre-configured demo application projects under 10```FreeRTOS/Demo``` directory. 11 12The easiest way to use FreeRTOS is to start with one of the pre-configured demo 13application projects. That way you will have the correct FreeRTOS source files 14included, and the correct include paths configured. Once a demo application is 15building and executing you can remove the demo application files, and start to 16add in your own application source files. See the 17[FreeRTOS Kernel Quick Start Guide](https://www.FreeRTOS.org/FreeRTOS-quick-start-guide.html) 18for detailed instructions and other useful links. 19 20Additionally, for FreeRTOS kernel feature information refer to the 21[Developer Documentation](https://www.FreeRTOS.org/features.html), 22and [API Reference](https://www.FreeRTOS.org/a00106.html). 23 24Also for contributing and creating a Pull Request please refer to 25[the instructions here](.github/CONTRIBUTING.md#contributing-via-pull-request). 26 27### Getting help 28 29If you have any questions or need assistance troubleshooting your FreeRTOS project, 30we have an active community that can help on the 31[FreeRTOS Community Support Forum](https://forums.freertos.org). 32 33## To consume FreeRTOS-Kernel 34 35### Consume with CMake 36 37If using CMake, it is recommended to use this repository using FetchContent. 38Add the following into your project's main or a subdirectory's `CMakeLists.txt`: 39 40- Define the source and version/tag you want to use: 41 42```cmake 43FetchContent_Declare( freertos_kernel 44 GIT_REPOSITORY https://github.com/FreeRTOS/FreeRTOS-Kernel.git 45 GIT_TAG main #Note: Best practice to use specific git-hash or tagged version 46) 47``` 48 49In case you prefer to add it as a git submodule, do: 50 51```bash 52git submodule add https://github.com/FreeRTOS/FreeRTOS-Kernel.git <path of the submodule> 53git submodule update --init 54``` 55 56- Add a freertos_config library (typically an INTERFACE library) The following assumes the directory structure: 57 - `include/FreeRTOSConfig.h` 58 59```cmake 60add_library(freertos_config INTERFACE) 61 62target_include_directories(freertos_config SYSTEM 63INTERFACE 64 include 65) 66 67target_compile_definitions(freertos_config 68 INTERFACE 69 projCOVERAGE_TEST=0 70) 71``` 72 73In case you installed FreeRTOS-Kernel as a submodule, you will have to add it as a subdirectory: 74 75```cmake 76add_subdirectory(${FREERTOS_PATH}) 77``` 78 79- Configure the FreeRTOS-Kernel and make it available 80 - this particular example supports a native and cross-compiled build option. 81 82```cmake 83set( FREERTOS_HEAP "4" CACHE STRING "" FORCE) 84# Select the native compile PORT 85set( FREERTOS_PORT "GCC_POSIX" CACHE STRING "" FORCE) 86# Select the cross-compile PORT 87if (CMAKE_CROSSCOMPILING) 88 set(FREERTOS_PORT "GCC_ARM_CA9" CACHE STRING "" FORCE) 89endif() 90 91FetchContent_MakeAvailable(freertos_kernel) 92``` 93 94- In case of cross compilation, you should also add the following to `freertos_config`: 95 96```cmake 97target_compile_definitions(freertos_config INTERFACE ${definitions}) 98target_compile_options(freertos_config INTERFACE ${options}) 99``` 100 101### Consuming stand-alone - Cloning this repository 102 103To clone using HTTPS: 104 105``` 106git clone https://github.com/FreeRTOS/FreeRTOS-Kernel.git 107``` 108 109Using SSH: 110 111``` 112git clone git@github.com:FreeRTOS/FreeRTOS-Kernel.git 113``` 114 115## Repository structure 116 117- The root of this repository contains the three files that are common to 118every port - list.c, queue.c and tasks.c. The kernel is contained within these 119three files. croutine.c implements the optional co-routine functionality - which 120is normally only used on very memory limited systems. 121 122- The ```./portable``` directory contains the files that are specific to a particular microcontroller and/or compiler. 123See the readme file in the ```./portable``` directory for more information. 124 125- The ```./include``` directory contains the real time kernel header files. 126 127- The ```./template_configuration``` directory contains a sample `FreeRTOSConfig.h` to help jumpstart a new project. 128See the [FreeRTOSConfig.h](examples/template_configuration/FreeRTOSConfig.h) file for instructions. 129 130### Code Formatting 131 132FreeRTOS files are formatted using the 133"[uncrustify](https://github.com/uncrustify/uncrustify)" tool. 134The configuration file used by uncrustify can be found in the 135[FreeRTOS/CI-CD-GitHub-Actions's](https://github.com/FreeRTOS/CI-CD-Github-Actions) 136[uncrustify.cfg](https://github.com/FreeRTOS/CI-CD-Github-Actions/tree/main/formatting) 137file. 138 139### Line Endings 140 141File checked into the FreeRTOS-Kernel repository use unix-style LF line endings 142for the best compatibility with git. 143 144For optimal compatibility with Microsoft Windows tools, it is best to enable 145the git autocrlf feature. You can enable this setting for the current 146repository using the following command: 147 148``` 149git config core.autocrlf true 150``` 151 152### Git History Optimizations 153 154Some commits in this repository perform large refactors which touch many lines 155and lead to unwanted behavior when using the `git blame` command. You can 156configure git to ignore the list of large refactor commits in this repository 157with the following command: 158 159``` 160git config blame.ignoreRevsFile .git-blame-ignore-revs 161``` 162 163### Spelling and Formatting 164 165We recommend using [Visual Studio Code](https://code.visualstudio.com), 166commonly referred to as VSCode, when working on the FreeRTOS-Kernel. 167The FreeRTOS-Kernel also uses [cSpell](https://cspell.org/) as part of its 168spelling check. The config file for which can be found at [cspell.config.yaml](cspell.config.yaml) 169There is additionally a 170[cSpell plugin for VSCode](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) 171that can be used as well. 172*[.cSpellWords.txt](.github/.cSpellWords.txt)* contains words that are not 173traditionally found in an English dictionary. It is used by the spellchecker 174to verify the various jargon, variable names, and other odd words used in the 175FreeRTOS code base are correct. If your pull request fails to pass the spelling 176and you believe this is a mistake, then add the word to 177*[.cSpellWords.txt](.github/.cSpellWords.txt)*. When adding a word please 178then sort the list, which can be done by running the bash command: 179`sort -u .cSpellWords.txt -o .cSpellWords.txt` 180Note that only the FreeRTOS-Kernel Source Files, [include](include), 181[portable/MemMang](portable/MemMang), and [portable/Common](portable/Common) 182files are checked for proper spelling, and formatting at this time. 183
){kind=link}
){kind=link}