Merge topic 'patch-UseEcos'

296c74cc5c UseEcos: Update documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10399

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(<var> <sources>...)
+
+  Adjusts the paths of given source files ``<sources>...`` and stores them into
+  a result variable named ``<var>``.
+
+  ``<var>``
+    Result variable name holding a new list of source files with adjusted paths.
+  ``<sources>...``
+    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(<name> <sources>...)
+
+  Creates an eCos application executable.
+
+  ``<name>``
+    The name of the executable.
+  ``<sources>...``
+    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     "<CMAKE_C_COMPILER> <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>")
   set(CMAKE_CXX_COMPILE_OBJECT   "<CMAKE_CXX_COMPILER> <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>")
-# special link commands for ecos-executables
+
+  # Special link commands for eCos executables.
   set(CMAKE_CXX_LINK_EXECUTABLE  "<CMAKE_CXX_COMPILER> <CMAKE_CXX_LINK_FLAGS> <OBJECTS> -o <TARGET> ${_ecos_EXTRA_LIBS} -nostdlib -nostartfiles -L${CMAKE_CURRENT_BINARY_DIR}/ecos/install/lib -Ttarget.ld ${ECOS_LD_MCPU}")
   set(CMAKE_C_LINK_EXECUTABLE    "<CMAKE_C_COMPILER> <CMAKE_C_LINK_FLAGS> <OBJECTS> -o <TARGET> ${_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()