From a3db429cc09433a99b1c3ac1382fb83d9681f09d Mon Sep 17 00:00:00 2001 From: Paul Helter Date: Sun, 23 Oct 2022 16:46:05 -0700 Subject: [PATCH] Added in documentation on how to consume from a main project. Added default PORT selection for native POSIX and MINGW platforms. --- CMakeLists.txt | 16 +++++++++++----- README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 58 insertions(+), 7 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 13c48325cba..7a3e081476d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,7 +1,7 @@ cmake_minimum_required(VERSION 3.15) # User is responsible to one mandatory option: -# FREERTOS_PORT +# FREERTOS_PORT, if not specified and native port detected, uses the native compile. # # User is responsible for one library target: # freertos_config ,typcially an INTERFACE library @@ -49,16 +49,14 @@ endif() set(FREERTOS_HEAP "4" CACHE STRING "FreeRTOS heap model number. 1 .. 5. Or absolute path to custom heap source file") # FreeRTOS port option -set(FREERTOS_PORT "" CACHE STRING "FreeRTOS port name") - if(NOT FREERTOS_PORT) - message(FATAL_ERROR " FREERTOS_PORT is not set. Please specify it from top-level CMake file (example):\n" + message(WARNING " FREERTOS_PORT is not set. Please specify it from top-level CMake file (example):\n" " set(FREERTOS_PORT GCC_ARM_CM4F CACHE STRING \"\")\n" " or from CMake command line option:\n" " -DFREERTOS_PORT=GCC_ARM_CM4F\n" " \n" " Available port options:\n" - " A_CUSTOM_PORT - Compiler: UserDefined Target: User Defined\n" + " A_CUSTOM_PORT - Compiler: User Defined Target: User Defined\n" " BCC_16BIT_DOS_FLSH186 - Compiler: BCC Target: 16 bit DOS Flsh186\n" " BCC_16BIT_DOS_PC - Compiler: BCC Target: 16 bit DOS PC\n" " CCS_ARM_CM3 - Compiler: CCS Target: ARM Cortex-M3\n" @@ -203,6 +201,14 @@ if(NOT FREERTOS_PORT) " CDK_THEAD_CK802 - Compiler: CDK Target: T-head CK802\n" " XCC_XTENSA - Compiler: XCC Target: Xtensa\n" " WIZC_PIC18 - Compiler: WizC Target: PIC18") + # Native FREERTOS_PORT for Linux and Windows MINGW builds + if(UNIX) + message(STATUS " Auto-Detected Unix, setting FREERTOS_PORT=GCC_POSIX") + set(FREERTOS_PORT GCC_POSIX CACHE STRING "FreeRTOS port name") + elseif(MINGW) + message(STATUS " Auto-Detected MINGW, setting FREERTOS_PORT=MSVC_MINGW") + set(FREERTOS_PORT MSVC_MINGW CACHE STRING "FreeRTOS port name") + endif() elseif((FREERTOS_PORT STREQUAL "A_CUSTOM_PORT") AND (NOT TARGET freertos_kernel_port) ) message(FATAL_ERROR " FREERTOS_PORT is set to A_CUSTOM_PORT. Please specify the custom port target with all necessary files. For example:\n" " Assuming a directory of:\n" diff --git a/README.md b/README.md index 52d78dd7924..d147f884077 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,53 @@ Additionally, for FreeRTOS kernel feature information refer to the [Developer Do ### Getting help If you have any questions or need assistance troubleshooting your FreeRTOS project, we have an active community that can help on the [FreeRTOS Community Support Forum](https://forums.freertos.org). -## Cloning this repository +## To consume FreeRTOS-Kernel + +### Consume with CMake +If using CMake, it is recommended to use this repository using FetchContent. +Add the following into your project's main or a subdirectory's `CMakeLists.txt`: + +- Define the source and version/tag you want to use: + +```cmake +FetchContent_Declare( freertos_kernel + GIT_REPOSITORY https://github.com/FreeRTOS/FreeRTOS-Kernel.git + GIT_TAG master #Note: Best practice to use specific git-hash or tagged version +) +``` + +- Add a freertos_config library (typically an INTERFACE library) The following assumes the directory structure: + - `include/FreeRTOSConfig.h` +```cmake +add_library(freertos_config INTERFACE) + +target_include_directories(freertos_config SYSTEM +INTERFACE + include +) + +target_compile_definitions(freertos_config + INTERFACE + projCOVERAGE_TEST=0 +) +``` + +- Configure the FreeRTOS-Kernel and make it available + - this particular example supports a native and cross-compiled build option. + +```cmake +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) +``` + +### Consuming stand-alone - Cloning this repository To clone using HTTPS: ``` @@ -36,4 +82,3 @@ FreeRTOS files are formatted using the "uncrustify" tool. The configuration file ### Spelling *lexicon.txt* contains words that are not traditionally found in an English dictionary. It is used by the spellchecker to verify the various jargon, variable names, and other odd words used in the FreeRTOS code base. If your pull request fails to pass the spelling and you believe this is a mistake, then add the word to *lexicon.txt*. Note that only the FreeRTOS Kernel source files are checked for proper spelling, the portable section is ignored. -