FreeRTOS-Kernel: The Standalone Kernel Repository and What It Actually Ships

What problem the standalone kernel repository solves

The kernel is three files at the root: list.c, queue.c and tasks.c. The README states plainly that the kernel is contained within these three files, with croutine.c implementing optional co-routine functionality normally used on very memory limited systems. Around them sit event_groups.c, stream_buffer.c and timers.c for the optional features, ./include for the real time kernel header files, and ./portable for the files specific to a particular microcontroller and compiler.

That layout is the point. If you have ever tried to lift a scheduler out of a vendor SDK, you know the failure mode: the kernel, the HAL, the demo tasks and the board support are tangled in one build system, and upgrading any of them means touching all of them. This repository separates the portable kernel from the demos. The README describes it as referenced as a submodule in FreeRTOS/FreeRTOS, which contains pre-configured demo application projects under FreeRTOS/Demo. So there are two consumption paths and they serve different people. Demo-first suits someone bringing up an unfamiliar board. Kernel-first suits someone who already has a build and wants a versioned dependency.

The intended audience is narrow and worth stating: embedded C developers on microcontrollers. This is not a Linux kernel, and the search question about the difference is answered by the repository structure itself. There is no memory management unit here, no process isolation, no user space. tasks.c schedules tasks within a single address space.

The mechanism: a fixed set of source files plus a port plus a config header

Three inputs determine what gets compiled. The first is the kernel sources you take from the root and from ./include. The second is the port, selected from ./portable, which holds the architecture and compiler specific code. The third is FreeRTOSConfig.h, which the README describes as a sample in examples/template_configuration, provided to help jumpstart a new project with instructions in the file itself.

CMake ties these together through two cache variables shown in the README. FREERTOS_HEAP selects the heap implementation, and the example sets it to 4. FREERTOS_PORT selects the port, and the example sets it to GCC_POSIX for a native build and GCC_ARM_CA9 when CMAKE_CROSSCOMPILING is true. Those two variables are the whole configuration surface at the CMake level; everything else, tick rate, stack sizes, priority counts, comes from the config header.

The heap number deserves attention because it is the decision most often made by accident. The README does not enumerate the heap schemes, so read the port and heap sources before choosing. Heap 4, the value in the example, is the one that pairs a heap with a free-and-coalesce routine, which matters if your application allocates and frees repeatedly rather than allocating everything at startup. If your tasks and queues are all created before the scheduler starts, a simpler scheme is defensible and cheaper. The repository gives you the choice and does not make it for you.

A fourth input is easy to miss. The README's CMake example defines a freertos_config INTERFACE library with target_include_directories pointing at an include directory that holds FreeRTOSConfig.h, and target_compile_definitions setting projCOVERAGE_TEST=0. Get that interface target wrong and the build fails at the first include, usually with a message about FreeRTOSConfig.h not being found rather than anything more helpful.

Installing FreeRTOS-Kernel with CMake FetchContent and a first build

The README recommends FetchContent when using CMake. The declaration below pins the repository and tag. Note the comment in the README itself: best practice is to use a specific git-hash or tagged version rather than the main branch, which is what the example shows for brevity.

FetchContent_Declare( freertos_kernel
  GIT_REPOSITORY https://github.com/FreeRTOS/FreeRTOS-Kernel.git
  GIT_TAG        main #Note: Best practice to use specific git-hash or tagged version
)

If you would rather vendor the code as a submodule, the README gives these two commands. The second initialises it after cloning, which is the step people forget when the submodule appears as an empty directory.

 git submodule add https://github.com/FreeRTOS/FreeRTOS-Kernel.git <path of the submodule>
git submodule update --init

Next, create the freertos_config library. The README assumes a directory structure with include/FreeRTOSConfig.h at its root. The SYSTEM keyword and the coverage definition are both taken from the README example.

add_library(freertos_config INTERFACE)

target_include_directories(freertos_config SYSTEM
INTERFACE
    include
)

target_compile_definitions(freertos_config
  INTERFACE
    projCOVERAGE_TEST=0
)

Then set the heap and port, and pull the kernel in. The cross-compiling branch is the part to keep: a native build and a cross build need different ports, and the README handles both in one block.

set( FREERTOS_HEAP "4" CACHE STRING "" FORCE)
# Select the native compile PORT
set( FREERTOS_PORT "GCC_POSIX" CACHE STRING "" FORCE)
# Select the cross-compile PORT
if (CMAKE_CROSSCOMPILING)
  set(FREERTOS_PORT "GCC_ARM_CA9" CACHE STRING "" FORCE)
endif()

FetchContent_MakeAvailable(freertos_kernel)

If you added the kernel as a submodule instead, the README says you must also add it as a subdirectory with add_subdirectory(${FREERTOS_PATH}). For cross compilation the README adds that you should pass your own definitions and options into freertos_config through target_compile_definitions and target_compile_options. What you should see after configuring is the kernel sources compiled into your target and vTaskStartScheduler available from the headers in ./include. The README does not describe the expected output of a first run, because there is no application here to run.

What this repository does not give you

There is no main function. The README is explicit that the easiest way to use FreeRTOS is to start with one of the pre-configured demo application projects, and that you can remove the demo application files once a demo is building and executing. If you clone this repository expecting something that compiles and blinks an LED, you will be disappointed; the demo projects live in FreeRTOS/FreeRTOS under FreeRTOS/Demo. The examples directory here holds a template configuration, a CMake example and a coverity directory, not applications.

The second limitation is port coverage. The README directs you to the readme file in ./portable for more information rather than listing supported architectures in the top-level document. If your compiler and core are not represented there, you are writing a port, which is a substantially larger task than configuring one. Nothing in the README promises that any given toolchain works.

The third is that the configuration header is a starting point, not a working configuration for your product. It is described as a sample to help jumpstart a new project. Tick rate, heap size, stack depths and the priority scheme all need to be chosen against your hardware, and the README does not walk through those choices. That is the right division of labour for a kernel repository, but it means the first hour is configuration work rather than coding.

Finally, this repository is not a distribution. It is a submodule target. If you want a release with a support commitment, the README notes that FreeRTOS-Kernel V11.1.0 source is part of the FreeRTOS 202406.00 LTS release, which points at the FreeRTOS-LTS repository instead of the main line. The latest releases listed for this repository are V11.3.1 and V11.3.0, which are newer than that LTS snapshot. Choosing between the newest tag and the LTS branch is a real decision, and it is one the README raises without resolving.

FreeRTOS-Kernel compared with Zephyr and vendor RTOS bundles

The obvious alternative for a new microcontroller project is Zephyr, and the difference is architectural rather than cosmetic. Zephyr is a full operating system distribution: it brings its own build system, device tree based hardware description, driver model, networking stacks and a large set of subsystems, all versioned together. FreeRTOS-Kernel brings a scheduler, queues, timers, event groups and stream buffers, and stops. Your drivers come from the silicon vendor, your build system is your own, and your board description is whatever your startup code and config header say it is.

That makes Zephyr the better choice when you want batteries included and are willing to adopt its configuration language and its release cadence. It makes FreeRTOS-Kernel the better choice when you already have a working vendor SDK, a linker script you trust, and a build you do not want to replace, and you only need preemptive scheduling and inter-task communication on top. The MIT licence here also differs from Zephyr's Apache 2.0, which matters to some legal reviews and not others.

The second alternative is the vendor RTOS bundle that ships with your MCU toolchain. Those bundles are convenient and often pin an old kernel version. Consuming this repository directly means you control the version, and the README's guidance to pin a git hash or tag is what makes that control real. The trade is that you now own the integration, including the port selection and the config header, rather than inheriting a vendor's tested combination.

Maintenance, versioning and licence

The repository is not archived, and the last push was on 2026-08-26, with V11.3.1 released on 2026-08-21 and V11.3.0 on 2026-03-30. The gap between V11.2.0 in March 2025 and V11.3.0 a year later is worth noting: this is not a project that ships a release every month, and a team that pins a tag should not expect frequent movement. That is usually fine for a kernel, where stability is the feature, but it means a bug you report may sit for a while.

Upgrade cost is dominated by the config header and the port, not by the kernel sources. Because FreeRTOSConfig.h lives in your tree and not in this repository, a kernel upgrade does not overwrite it, and that is the main reason upgrades are tractable. The risk is the opposite: your config can drift from what the current kernel expects, and the README does not document a migration procedure between major versions. Read the release notes for the tag you are moving to and diff your config against examples/template_configuration.

The licence is MIT, per the repository metadata. MIT is permissive and imposes no source disclosure obligation, which is why it is common in commercial firmware. This is not legal advice, and the licence text in LICENSE.md is what governs; if your organisation requires attribution notices in the product documentation, read that file rather than this paragraph.

Two contributor details are worth knowing even if you never send a patch. FreeRTOS files are formatted with uncrustify using a configuration file held in the FreeRTOS/CI-CD-GitHub-Actions repository, so a patch formatted by hand will likely be reformatted. And the repository uses cSpell with a word list in .github/.cSpellWords.txt; the README says that if your pull request fails the spelling check and you believe it is a mistake, you add the word to that list. Both of those are gates, not suggestions.

Editorial conclusion

Adopt FreeRTOS-Kernel if you are building firmware for a microcontroller and want the scheduler, queues, timers and stream buffers as source you compile yourself, with a port for your architecture already in ./portable. Do not adopt it if you expect a runnable program after cloning: this repository has no demo application, and the README points you at FreeRTOS/FreeRTOS for pre-configured demos. Before committing, verify that a port exists for your compiler and core, that FREERTOS_HEAP and FREERTOS_PORT in your CMake configuration match your memory strategy, and that your FreeRTOSConfig.h comes from examples/template_configuration rather than a demo project you copied years ago.

Frequently asked questions

Official sources

1. FreeRTOS/FreeRTOS-Kernel on GitHub
2. License: MIT
3. Project website
4. README
5. Releases