updated readme

Author: robamu

README.md

@@ -1,8 +1,13 @@
 # RTEMS CMake Build Support
 
-This repository contains the first version of a possible RTEMS CMake build support. 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 build their RTEMS application with CMake. The support has been written as generic as possible.
+This repository contains the first version of a possible RTEMS CMake build support. 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 build their RTEMS application with CMake. The support has been written as generic as possible and only required a few lines of code is the application `CMakeLists.txt` file and some necessary variables set to determine compiler information.
 
-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.
+It is assumed that the RTEMS tools and the BSPs have already been built. If you are a beginner and this is not the case, it is recommended to have a look at [this demo](https://github.com/rmspacefish/rtems-demo) or the [QuickStart](https://docs.rtems.org/branches/master/user/start/index.html) to get started with RTEMS.
+
+The usual way to set up a cross-compile project in CMake is to specify a CMake toolchain file. The CMake RTEMS support uses a combination of the supplied RTEMS BSP, 
+RTEMS version, RTEMS prefix and the `pkgconfig` utility to set up the RTEMS environment properly so that application developers can focus on their application.
+
+This is still a prototype. Simple applications have been tested, but no larger projects have been compiled with this build support yet.
 The compilation of simple applications was tested on Windows 10 and Ubuntu 20.04
 
 ## How to use
@@ -23,62 +28,52 @@ set(RTEMS_CONFIG_DIR
 )
 ```
 
-It is also recommended (and necessary on Windows) to add the following lines before 
-the `project()` call in the application `CMakeLists.txt`:
+We need to prepare some internal environmental variables for the CMake toolchain file and we also need to process information like the supplied `RTEMS_BSP` and `RTEMS_PREFIX` for the PKG config utility.
+Add the following lines of code before the `project` call in your `CMakeLists.txt`
+to call `rtems_pre_project_config` and  pass `RTEMS_PREFIX` and `RTEMS_BSP` into the function call.
 
 ```sh
-set(CMAKE_SYSTEM_NAME Generic)
-set(CMAKE_C_COMPILER_WORKS 1)
-set(CMAKE_CXX_COMPILER_WORKS 1)
-set(CMAKE_CROSSCOMPILING 1)
+include(${RTEMS_CONFIG_DIR}/RTEMSPreProjectConfig.cmake)
+rtems_pre_project_config(${RTEMS_PREFIX} ${RTEMS_BSP})
 ```
 
-This will disable the compiler checks for the standard C/C++ compiler.
-
+Now the CMake environment is prepared for the toolchan file. We set the `CMAKE_TOOLCHAIN_FILE` to CMake can set up the compilers and required RTEMS flags properly in the `project` call:
 
-If this repository was cloned inside the application root, the path can be 
-set to `${CMAKE_CURRENT_SOURCE_DIRECTORY}/rtems-cmake`.
-
-After that, include the general configuration file with the following line:
+Add the following lines of code before the `project` call:
 
 ```sh
-include("${RTEMS_CONFIG_DIR}/RTEMSConfig.cmake")
+set(CMAKE_TOOLCHAIN_FILE ${RTEMS_CONFIG_DIR}/RTEMSToolchain.cmake) 
 ```
 
-And then call the configuration function:
+Finally, you can add the following lines to call the post-project configuration, 
+passing the target name into the function call
 
 ```sh
-rtems_general_config(<TargetName> <RTEMS Prefix> <RTEMS BSP>)
+include("${RTEMS_CONFIG_DIR}/RTEMSPostProjectConfig.cmake")
+rtems_post_project_config(${TARGET_NAME})
 ```
 
-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.
+This is not mandatory yet, but is useful for additional debug information (if `RTEMS_VERBOSE` is set to `TRUE`) and might become useful in the future if some additional target specific properties need to be set for RTEMS.
 
-It is recommended to either hardcode mandatory values like the prefix and BSP path in the application `CMakeLists.txt`
-(especially when using the CMake GUI) or to supply them via command line and write scripts to ease this process.
+It is recommended to either hardcode mandatory values like the prefix and BSP path in the application `CMakeLists.txt` (especially when using the CMake GUI) or to supply them via command line and write scripts to ease this process.
 
-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
 
 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: 
-
-Extract the necessary compiler and linker flags for the RTEMS build from the pkgconfig file
-for the specific BSP. This file will generally be located inside the `lib/pkgconfig` folder of the RTEMS tools folder. Add these flags in the `RTEMSHardware.cmake` file for your specific BSP.
+If this becomes necessary after all, follow these steps:
 
-When building with CMake, `-v` can be added to verify the flags.
+Extract the necessary compiler and linker flags for the RTEMS build from the pkgconfig file for the specific BSP. This file will generally be located inside the `lib/pkgconfig` folder of the RTEMS tools folder. Add these flags manually before the `project` file call (see `RTEMSToolchain.cmake` for examples) for your specific BSP.
 
 ## Example
 

RTEMSPostProjectConfig.cmake

@@ -1,4 +1,4 @@
-function(rtems_post_project_config)
+function(rtems_post_project_config TARGET_NAME)
 
 if(RTEMS_VERBOSE)
 	message(STATUS "########################################################")