From 296c74cc5cf29f737702be6353b6603c2094f409 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Thu, 27 Feb 2025 17:37:13 +0100 Subject: UseEcos: Update documentation - Module macros described as a list with the usual RST syntax. - Mention of internal macro ecos_add_target_lib() removed, as it is internal implementation meant for the ecos_add_executable(). - Documentation from internal comments moved to the main docs header. - Variable descriptions updated. - Internal comments adjusted for readability. --- Modules/UseEcos.cmake | 214 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 138 insertions(+), 76 deletions(-) diff --git a/Modules/UseEcos.cmake b/Modules/UseEcos.cmake index 0b07723..e2cdd7c 100644 --- a/Modules/UseEcos.cmake +++ b/Modules/UseEcos.cmake @@ -7,39 +7,120 @@ UseEcos This module defines variables and macros required to build eCos application. -This file contains the following macros: +Macros +^^^^^^ -``ECOS_ADD_INCLUDE_DIRECTORIES()`` - add the eCos include dirs -``ECOS_ADD_EXECUTABLE(name source1 ... sourceN )`` - create an eCos executable -``ECOS_ADJUST_DIRECTORY(VAR source1 ... sourceN )`` - adjusts the path of the source files and puts the result into ``VAR`` +This module defines the following macros: + +.. command:: ecos_add_include_directories + + .. code-block:: cmake + + ecos_add_include_directories() + + Adds the eCos include directories for the current `CMakeLists.txt` file. + +.. command:: ecos_adjust_directory + + .. code-block:: cmake + + ecos_adjust_directory( ...) + + Adjusts the paths of given source files ``...`` and stores them into + a result variable named ````. + + ```` + Result variable name holding a new list of source files with adjusted paths. + ``...`` + A list of relative or absolute source files to adjust their paths. + + Use this macro when the actual sources are located one level upwards. A + ``../`` has to be prepended in front of every source file that is given as a + relative path. + +.. command:: ecos_add_executable + + .. code-block:: cmake + + ecos_add_executable( ...) + + Creates an eCos application executable. + + ```` + The name of the executable. + ``...`` + A list of all source files, where the path has been adjusted beforehand by + calling the ``ecos_adjust_directory()``. + + This macro also sets the ``ECOS_DEFINITIONS`` local variable, holding some + common compile definitions. Macros for selecting the toolchain: -``ECOS_USE_ARM_ELF_TOOLS()`` - enable the ARM ELF toolchain for the directory where it is called -``ECOS_USE_I386_ELF_TOOLS()`` - enable the i386 ELF toolchain for the directory where it is called -``ECOS_USE_PPC_EABI_TOOLS()`` - enable the PowerPC toolchain for the directory where it is called +.. command:: ecos_use_arm_elf_tools + + .. code-block:: cmake + + ecos_use_arm_elf_tools() + + Enables the ARM ELF toolchain for the directory where it is called. Use this + macro, when compiling for the xscale processor. + +.. command:: ecos_use_i386_elf_tools -It contains the following variables: + .. code-block:: cmake -``ECOS_DEFINITIONS`` + ecos_use_i386_elf_tools() + + Enables the i386 ELF toolchain for the directory where it is called. + +.. command:: ecos_use_ppc_eabi_tools + + .. code-block:: cmake + + ecos_use_ppc_eabi_tools() + + Enables the PowerPC toolchain for the directory where it is called. + +Variables +^^^^^^^^^ + +Module also defines the following variables: ``ECOSCONFIG_EXECUTABLE`` + Cache variable that contains a path to the ``ecosconfig`` executable (the eCos + configuration program). ``ECOS_CONFIG_FILE`` - defaults to ecos.ecc, if your eCos configuration file has a different name, adjust this variable for internal use only: + A local variable that defaults to ``ecos.ecc``. If eCos configuration file + has a different name, adjust this variable before calling the + ``ecos_add_executable()``. + +Examples +^^^^^^^^ + +.. code-block:: cmake + + # CMakeLists.txt -:: + include(UseEcos) - ECOS_ADD_TARGET_LIB + # Add the eCos include directories. + ecos_add_include_directories() + + # Include the file with the eCos sources list. This file, for example, defines + # a list of eCos sources: + # set(sources file_1.cxx file_2.cxx file_3.cxx) + include(../ProjectSources.txt) + + # When using such directory structure, relative source paths must be adjusted: + ecos_adjust_directory(adjusted_sources ${sources}) + + # Create eCos executable. + ecos_add_executable(ecos_app ${adjusted_sources}) #]=======================================================================] -# first check that ecosconfig is available +# First check that ecosconfig is available. find_program(ECOSCONFIG_EXECUTABLE NAMES ecosconfig) if(NOT ECOSCONFIG_EXECUTABLE) message(SEND_ERROR "ecosconfig was not found. Either include it in the system path or set it manually using ccmake.") @@ -47,14 +128,15 @@ else() message(STATUS "Found ecosconfig: ${ECOSCONFIG_EXECUTABLE}") endif() -# check that ECOS_REPOSITORY is set correctly +# Check that ECOS_REPOSITORY is set correctly. if (NOT EXISTS $ENV{ECOS_REPOSITORY}/ecos.db) message(SEND_ERROR "The environment variable ECOS_REPOSITORY is not set correctly. Set it to the directory which contains the file ecos.db") else () message(STATUS "ECOS_REPOSITORY is set to $ENV{ECOS_REPOSITORY}") endif () -# check that tclsh (coming with TCL) is available, otherwise ecosconfig doesn't work +# Check that tclsh (coming with TCL) is available, otherwise ecosconfig doesn't +# work. find_package(Tclsh) if (NOT TCL_TCLSH) message(SEND_ERROR "The TCL tclsh was not found. Please install TCL, it is required for building eCos applications.") @@ -62,98 +144,83 @@ else () message(STATUS "tlcsh found: ${TCL_TCLSH}") endif () -#add the global include-directories -#usage: ECOS_ADD_INCLUDE_DIRECTORIES() macro(ECOS_ADD_INCLUDE_DIRECTORIES) -#check for ProjectSources.txt one level higher + # Check for ProjectSources.txt one level higher. if (EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/../ProjectSources.txt) include_directories(${CMAKE_CURRENT_SOURCE_DIR}/../) else () include_directories(${CMAKE_CURRENT_SOURCE_DIR}/) endif () -#the ecos include directory + # The ecos include directory. include_directories(${CMAKE_CURRENT_BINARY_DIR}/ecos/install/include/) - endmacro() - -#we want to compile for the xscale processor, in this case the following macro has to be called -#usage: ECOS_USE_ARM_ELF_TOOLS() macro (ECOS_USE_ARM_ELF_TOOLS) set(CMAKE_CXX_COMPILER "arm-elf-c++") set(CMAKE_COMPILER_IS_GNUCXX 1) set(CMAKE_C_COMPILER "arm-elf-gcc") set(CMAKE_AR "arm-elf-ar") set(CMAKE_RANLIB "arm-elf-ranlib") -#for linking + # For linking. set(ECOS_LD_MCPU "-mcpu=xscale") -#for compiling + # For compiling. add_definitions(-mcpu=xscale -mapcs-frame) -#for the obj-tools + # For the obj-tools. set(ECOS_ARCH_PREFIX "arm-elf-") endmacro () -#usage: ECOS_USE_PPC_EABI_TOOLS() macro (ECOS_USE_PPC_EABI_TOOLS) set(CMAKE_CXX_COMPILER "powerpc-eabi-c++") set(CMAKE_COMPILER_IS_GNUCXX 1) set(CMAKE_C_COMPILER "powerpc-eabi-gcc") set(CMAKE_AR "powerpc-eabi-ar") set(CMAKE_RANLIB "powerpc-eabi-ranlib") -#for linking + # For linking. set(ECOS_LD_MCPU "") -#for compiling + # For compiling. add_definitions() -#for the obj-tools + # For the obj-tools. set(ECOS_ARCH_PREFIX "powerpc-eabi-") endmacro () -#usage: ECOS_USE_I386_ELF_TOOLS() macro (ECOS_USE_I386_ELF_TOOLS) set(CMAKE_CXX_COMPILER "i386-elf-c++") set(CMAKE_COMPILER_IS_GNUCXX 1) set(CMAKE_C_COMPILER "i386-elf-gcc") set(CMAKE_AR "i386-elf-ar") set(CMAKE_RANLIB "i386-elf-ranlib") -#for linking + # For linking. set(ECOS_LD_MCPU "") -#for compiling + # For compiling. add_definitions() -#for the obj-tools + # For the obj-tools. set(ECOS_ARCH_PREFIX "i386-elf-") endmacro () - -#since the actual sources are located one level upwards -#a "../" has to be prepended in front of every source file -#call the following macro to achieve this, the first parameter -#is the name of the new list of source files with adjusted paths, -#followed by all source files -#usage: ECOS_ADJUST_DIRECTORY(adjusted_SRCS ${my_srcs}) macro(ECOS_ADJUST_DIRECTORY _target_FILES ) foreach (_current_FILE ${ARGN}) get_filename_component(_abs_FILE ${_current_FILE} ABSOLUTE) - if (NOT ${_abs_FILE} STREQUAL ${_current_FILE}) - get_filename_component(_abs_FILE ${CMAKE_CURRENT_SOURCE_DIR}/../${_current_FILE} ABSOLUTE) - endif () + if (NOT ${_abs_FILE} STREQUAL ${_current_FILE}) + get_filename_component(_abs_FILE ${CMAKE_CURRENT_SOURCE_DIR}/../${_current_FILE} ABSOLUTE) + endif () list(APPEND ${_target_FILES} ${_abs_FILE}) endforeach () endmacro() -# the default ecos config file name -# maybe in future also out-of-source builds may be possible +# The default eCos config file name. Maybe in future also out-of-source builds +# may be possible. set(ECOS_CONFIG_FILE ecos.ecc) -#creates the dependency from all source files on the ecos target.ld, -#adds the command for compiling ecos +# Internal macro that creates the dependency from all source files on the eCos +# target.ld and adds the command for compiling eCos. macro(ECOS_ADD_TARGET_LIB) -# when building out-of-source, create the ecos/ subdir + # When building out-of-source, create the ecos/ subdir. if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/ecos) file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/ecos) endif() -#sources depend on target.ld + # Sources depend on target.ld. set_source_files_properties( ${ARGN} PROPERTIES @@ -174,40 +241,37 @@ macro(ECOS_ADD_TARGET_LIB) add_custom_target( ecos make -C ${CMAKE_CURRENT_BINARY_DIR}/ecos/ DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/ecos/makefile ) endmacro() -# get the directory of the current file, used later on in the file +# Get the directory of the current file, used later on in the file. get_filename_component( ECOS_CMAKE_MODULE_DIR ${CMAKE_CURRENT_LIST_FILE} PATH) -#macro for creating an executable ecos application -#the first parameter is the name of the executable, -#the second is the list of all source files (where the path -#has been adjusted beforehand by calling ECOS_ADJUST_DIRECTORY() -#usage: ECOS_ADD_EXECUTABLE(my_app ${adjusted_SRCS}) macro(ECOS_ADD_EXECUTABLE _exe_NAME ) - #definitions, valid for all ecos projects - #the optimization and "-g" for debugging has to be enabled - #in the project-specific CMakeLists.txt + # Definitions, valid for all eCos projects. + # The optimization and "-g" for debugging has to be enabled in the + # project-specific CMakeLists.txt. add_definitions(-D__ECOS__=1 -D__ECOS=1) set(ECOS_DEFINITIONS -Wall -Wno-long-long -pipe -fno-builtin) -#the executable depends on ecos target.ld - ECOS_ADD_TARGET_LIB(${ARGN}) + # The executable depends on eCos target.ld. + ecos_add_target_lib(${ARGN}) -# when using nmake makefiles, the custom buildtype suppresses the default cl.exe flags -# and the rules for creating objects are adjusted for gcc + # When using nmake makefiles, the custom buildtype suppresses the default + # cl.exe flags and the rules for creating objects are adjusted for gcc. set(CMAKE_BUILD_TYPE CUSTOM_ECOS_BUILD) set(CMAKE_C_COMPILE_OBJECT " -o -c ") set(CMAKE_CXX_COMPILE_OBJECT " -o -c ") -# special link commands for ecos-executables + + # Special link commands for eCos executables. set(CMAKE_CXX_LINK_EXECUTABLE " -o ${_ecos_EXTRA_LIBS} -nostdlib -nostartfiles -L${CMAKE_CURRENT_BINARY_DIR}/ecos/install/lib -Ttarget.ld ${ECOS_LD_MCPU}") set(CMAKE_C_LINK_EXECUTABLE " -o ${_ecos_EXTRA_LIBS} -nostdlib -nostartfiles -L${CMAKE_CURRENT_BINARY_DIR}/ecos/install/lib -Ttarget.ld ${ECOS_LD_MCPU}") -# some strict compiler flags + + # Some strict compiler flags. set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wstrict-prototypes") set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Woverloaded-virtual -fno-rtti -Wctor-dtor-privacy -fno-strict-aliasing -fno-exceptions") add_executable(${_exe_NAME} ${ARGN}) set_target_properties(${_exe_NAME} PROPERTIES SUFFIX ".elf") -#create a binary file + # Create a binary file. add_custom_command( TARGET ${_exe_NAME} POST_BUILD @@ -215,7 +279,7 @@ macro(ECOS_ADD_EXECUTABLE _exe_NAME ) ARGS -O binary ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.elf ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.bin ) -#and an srec file + # And an srec file. add_custom_command( TARGET ${_exe_NAME} POST_BUILD @@ -223,7 +287,7 @@ macro(ECOS_ADD_EXECUTABLE _exe_NAME ) ARGS -O srec ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.elf ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.srec ) -#add the created files to the clean-files + # Add the created files to the clean-files. set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_CLEAN_FILES "${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.bin" "${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.srec" @@ -233,7 +297,6 @@ macro(ECOS_ADD_EXECUTABLE _exe_NAME ) add_custom_target(normalclean ${CMAKE_MAKE_PROGRAM} clean WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}) add_dependencies (ecosclean normalclean) - add_custom_target( listing COMMAND echo -e \"\\n--- Symbols sorted by address ---\\n\" > ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.lst COMMAND ${ECOS_ARCH_PREFIX}nm -S -C -n ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.elf >> ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.lst @@ -241,5 +304,4 @@ macro(ECOS_ADD_EXECUTABLE _exe_NAME ) COMMAND ${ECOS_ARCH_PREFIX}nm -S -C -r --size-sort ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.elf >> ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.lst COMMAND echo -e \"\\n--- Full assembly listing ---\\n\" >> ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.lst COMMAND ${ECOS_ARCH_PREFIX}objdump -S -x -d -C ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.elf >> ${CMAKE_CURRENT_BINARY_DIR}/${_exe_NAME}.lst ) - endmacro() -- cgit v0.12