documentation improved significantly

Author: robamu

README.md

@@ -1,15 +1,60 @@
-# rtems-cmake
+# RTEMS CMake Build Support
 
-This repostiory contains the first version of a possible RTEMS CMake build aupport. The intention is to export the RTEMS specific configuration of the cross compiler toolchain and the flags to external `*.cmake` files so the application `CMakeLists.txt` can stay clean, similarly to the `rtems_waf` support.
+This repostiory contains the first version of a possible RTEMS CMake build aupport. The intention is to provide most CMake configuration to perform cross-compiling of RTEMS applications and provide a decent starting point for developers which would like to use RTEMS. The support has been written as generic as possible.
+
+This is still a prototype. Simple applications have been tested, but it has not been attempted to link an additional library for an application yet.
 
 ## How to use
 
-Include the `RTEMSGeneric.cmake` file in CMake and call the `rtems_generic_config` function, passing the RTEMS installation path (also commonly called prefix)
+Clone this repository. This does not necesarilly have to be in the application root path, but the RTEMS configuration path (the folder containing the `*.cmake` files) needs to be specified in this case.
+
+```sh
+git clone https://github.com/rmspacefish/rtems-cmake.git
+```
+
+After that, it is recommended to set the path to the RTEMS CMake support with the 
+following line in the application `CMakeLists.txt`
+
+```sh
+set(RTEMS_CONFIG_DIR
+	"<Path to RTEMS CMake support folder>"
+	 CACHE FILEPATH "Directory containing the RTEMS *.cmake files"
+)
+```
+
+If this repository was cloned inside the application root, the path can be 
+set to `${CMAKE_CURRENT_SOURCE_DIRECTORY}`.
+
+After that, include the general configuration file with the following line:
+
+```sh
+include("${RTEMS_CONFIG_DIR}/RTEMSConfig.cmake")
+```
+
+And then call the configuration function:
+
+```sh
+rtems_general_config(${CMAKE_PROJECT_NAME} ${RTEMS_PREFIX} ${RTEMS_BSP})
+```
+
+This function will call the the `rtems_generic_config` function internally to set up the cross-compiler, using the provided RTEMS prefix and the BSP name,
 and the RTEMS BSP (e.g. sparc/erc32) to this function.
 
+After that, it will call the the function `rtems_hw_config` which will assign necessary compiler and linker flags to the provided target.
+
+## Optional configuration of the CMake support
+
+The RTEMS CMake build support can be configured either by passing configuration options prepended with `-D` to the build command or by setting these build variables in the application `CMakeLists.txt` before calling the build support. Following options are available
+
+ - `RTEMS_VERSION`: Can be specified manually. If this is not specified, the CMake build support will attempt to extract the version number from the RTEMS prefix (last letter of path). This variable needs to be valid for the RTEMS support to work!
+ - `RTEMS_VERBOSE`: Enable additional diagnostic output.
+ - `RTEMS_SCAN_PKG_CONFIG`: The RTEMS CMake support will try to read the pkgconfig files to extract compile and link flag options.
+ - `RTEMS_TOOLS`: Can be specified if the RTEMS tools folder. Can be different from the prefix but will be equal to the prefix for most users.
+ - `RTEMS_PATH`: Folder containing the RTEMS installation (BSPs). Can be different from the prefix but will be equal to the prefix for most users.
+
 ## Extending the build system support
 
-This is still a prototype. It has been tested for the Hello World demo from the RTEMS quick start guide which uses the `sparc/erc32` BSP and for a STM32 blinky using the `arm/stm32h7` BSP.
+It is possible to read the pkfconfig files now, so extending the manual build configuration might not be necessary in the future.
 
 Extending the build support is relatively easy: 
 

RTEMSConfig.cmake

@@ -14,30 +14,42 @@
 #    the RTEMS_BSP variable.
 #
 # Other variables which can be provided by the developer via command line
-# as well:
+# or in the application CMake file as well:
 #
-# 1. RTEMS_VERSION:
+# 1. RTEMS_CONFIG_DIR: The application will assume that all other configuration
+#    files are located in this path or relative to this path. If this is not set
+#    it will be set to the ${CMAKE_CURRENT_SOURCE_DIR}/rtems-cmake
+# 2. RTEMS_VERSION:
 #    The user can supply RTEMS_VERSION to specify the RTEMS version
 #    manually. This is required to determine the toolchains to use. If no
 #    RTEMS_VERSION is supplied, this CMake file will try to autodetermine the 
 #    RTEMS version from the supplied tools path.
-# 2. RTEMS_TOOLS:
+# 3. RTEMS_TOOLS:
 #	 The user can provide this filepath variable if the RTEMS tools path is 
 #    not equal to the RTEMS prefix.
-# 3. RTEMS_PATH:
+# 4. RTEMS_PATH:
 #	 The user can provide this filepath variable if the RTEMS path (containg
 #    the BSPs) is not equal to the RTEMS prefix.
-# 4. RTEMS_VERBOSE:
+# 5. RTEMS_VERBOSE:
 #    Verbose debug output for the CMake handling.
-# 5. RTEMS_SCAN_PKG_CONFIG:
+# 6. RTEMS_SCAN_PKG_CONFIG:
 #    CMake will try to scan the pkgconfig file for the specified Architecture-
 #    Version-BSP combination to find the compiler and linker flags.
 # 
 # Any additional arguments will be passed on to the subfunctions here.
 
 function(rtems_general_config TARGET_NAME RTEMS_PREFIX RTEMS_BSP_PAIR)
 
-	include(${RTEMS_CONFIG_DIRECTORY}/RTEMSGeneric.cmake)
+	message(STATUS ${RTEMS_CONFIG_DIR})
+	if(NOT RTEMS_CONFIG_DIR) 
+		message(STATUS 
+			"RTEMS_CONFIG_DIR not set. Assuming  the CMake support was "
+			"cloned in the application source directory.."
+		)
+		set(RTEMS_CONFIG_DIR ${CMAKE_CURRENT_SOURCE_DIR}/rtems-cmake)
+	endif()
+	
+	include(${RTEMS_CONFIG_DIR}/RTEMSGeneric.cmake)
 	rtems_generic_config(${TARGET_NAME} ${RTEMS_PREFIX} ${RTEMS_BSP_PAIR} ${ARGN})
 
 	# Not an ideal solution but it will do for now because the number of 
@@ -57,7 +69,7 @@ function(rtems_general_config TARGET_NAME RTEMS_PREFIX RTEMS_BSP_PAIR)
 		set(CMAKE_SYSTEM_PROCESSOR ${CMAKE_SYSTEM_PROCESSOR} PARENT_SCOPE)
 	endif()
 
-	include(${RTEMS_CONFIG_DIRECTORY}/RTEMSHardware.cmake)
+	include(${RTEMS_CONFIG_DIR}/RTEMSHardware.cmake)
 	rtems_hw_config(${TARGET_NAME} ${RTEMS_PREFIX} ${RTEMS_BSP_PAIR} ${ARGN})
 
 	# No propagation necessary here because we can use target specific settings.