Concerto 自述

本文参考tda4，翻译concerto的README，旨在记录和简单说明Concerto的原理和使用。

Concerto 自述

它是啥?

Concerto是一个简单的单遍、非递归、完全依赖管理的Makefile系统

如何工作的

Concerto 会在DIRECTORIES变量指定的目录(及其对应的子目录)中查找名为concerto.mak的子编译文件。它将“包括”每个模块的concerto.mak文件到整体的构建系统，并解析与该模块相关的所有构建相关宏。这样，所有的concerto.mak makefiles读取一次，所以是“single pass”。Concerto构建系统的makefiles类似于prelude.mak 和finale.mak，每个模块读取一次(以及其中的子makefile)。这些宏用于定义建立整个构建系统的完整依赖树所需的make-target宏。

构建系统文件:

• definitions.mak - useful macros（有用的宏定义）
• rules.mak - internal top level file.（内部顶级文件）
• os.mak - determines host os.（确定主机操作系统）
• machine.mak - determines host cpu.（确定主机CPU）
• target.mak - determines target variables and build system include paths, variables. This can be replaced (see above).（确定目标变量和构建系统包括路径、变量。这是可以替换的(见上面)）
• scm.mak - tries to extract SCM version information (SVN/GIT) （试图提取SCM版本信息(SVN/GIT)）
• prelude.mak and finale.mak - generates non-recursive build system macros and variables per module（为每个模块生成非递归的构建系统宏和变量）
• compilers/* - Compiler specific files（编译器特定的文件）
• os/* - OS specific installing/removing rules（操作系统的安装/移除规则）
• tools/* - tools specific rules.（工具的具体规则）

如何使用

• 下载或复制concerto文件夹到您的构建系统的某处，指令： git clone ssh://$USER@gitorious.design.ti.com:build-systems/concerto.git
• 在项目顶部创建一个Makefile，其中包含以下内容:

每个项目的顶级Makefile

# Path to concerto install or use environment variable（concerto安装或使用环境变量的路径）
CONCERTO_ROOT ?= concerto
# [OPTIONAL] if DIRECTORIES is not specified concerto assumes "source"
DIRECTORIES  := src docs
# [OPTIONAL] BUILD_TARGET is used to reflect specific needs of your build system.（BUILD_TARGET用于反映构建系统的特定需求。）
# if not specified concerto's default target.mak is used instead
BUILD_TARGET := $(abspath .)/target.mak
# This calls concerto
include $(CONCERTO_ROOT)/rules.mak

concerto.mak文件内容

concerto.mak 文件可以包含以下内容(虽然通常较短):

_MODULE=<optional module name>#可选的模块名称
include $(PRELUDE)
TARGET=<name of the object created>#创建的对象名称
TARGETTYPE=<exe|library|dsmo|prebuilt|jar>#创建的对象类型
CSOURCES=<list of C files>#C文件列表
CPPSOURCES=<list of C++ files>#C++ 文件列表
ASSEMBLY=<list of .S Files>#.S文件列表
KCSOURCES=<list of KernelC .k files>
IDIRS+=<include directories>#头文件目录
DEFS+=<defines>
STATIC_LIBS=<static libraries within the build system>#构建系统中的静态库
SHARED_LIBS=<shared libraries within the build system>#构建系统中的共享库
SYS_STATIC_LIBS=<static libraries outside the build system>#构建系统外部的静态库，也就是系统静态库
SYS_SHARED_LIBS=<shared libraries outside the build system>#构建系统外部的共享库，也就是系统共享库
LINKER_FILES=<list of linker files within the build system>#生成系统内链接器文件的列表
PREBUILT=<It specifies a single resource to be copied into the target output, only used with the prebuilt TARGETTYPE>#它指定要复制到目标输出中的单个资源，仅与预构建的TARGETTYPE一起使用
include $(FINALE)

一个典型 concerto.mak 是比较小的:

include $(PRELUDE)
TARGET=mytest
TARGETTYPE=exe
SYS_STATIC_LIBS+=sosal
CSOURCES=main.c
include $(FINALE)

内部变量

The following variables and macros are available for use in a concerto.mak file.
以下变量和宏可用于 concerto.mak文件。

• _MODULE - the name of the module (if not defined, the containing folder name will be used). 模块的名称(如果没有定义，将使用包含的文件夹名称)。
• TARGET - the name of the component to build. Prefixes and postfixes will be added by the build system, do not add them yourself. 要构建的组件的名称。前缀和后缀将由构建系统添加，请不要自己添加它们。
• TARGETTYPE - possible values are:构建类型有以下几种值：
  • exe - binary executable（二进制可执行文件）
  • library - static library（静态库）
  • dsmo - dynamic shared library（动态共享库）
  • prebuilt - a prebuilt binary（一个预先构建的二进制）
  • jar - a Java jar file（一个Java jar文件）
  • doxygen - A doxygen build（doxygen构建）
  • deb - A debian package (control file is required)（debian包(控制文件是必需的)）
• SYS_SHARED_LIBS - dynamic libraries for which no dependencies are generated (which implies that they are outside the build system).（没有为其生成依赖关系的动态库(这意味着它们位于构建系统之外)）
• SYS_STATIC_LIBS - static libraries for which no dependencies are generated (which implies that they are outside the build system). （没有为其生成依赖关系的动态库(这意味着它们位于构建系统之外)）
• SHARED_LIBS - dynamic libraries for which dependencies are generated (which implies that they are intside the build system).（生成依赖项的动态库(这意味着它们位于构建系统内部)）
• STATIC_LIBS - static libraries for which dependencies are generated (which implies that they are inside the build system).（生成依赖项的静态库(这意味着它们位于构建系统内部)）
• ASSEMBLY - S files which must be in the same folder.
• CSOURCES - C files which must be in the same folder.
• CPPSOURCES - C++ files which must be in the same folder.
• JSOURCES - Java files for Jar targets
• IDIRS - include directories （头文件的路径）
• LDIRS - library link path （链接库的路径）
• DEFS - #defines to pass to the compiler（定义传递给编译器的参数）

有用的宏

# list of files with extension .ext in "dir" and any sub-directory of "dir"
# 在dir目录及其子目录下以.ext为扩展名的文件列表
$(call all-type-files-in,<ext>,<dir>)
# list of files with extension .ext that exist inside this module (including any sub-directories)
# 存在于此模块内的扩展名为.ext的文件列表(包括任何子目录)
$(call all-type-files,<ext>)
# list of c files c that exist inside this module (including any sub-directories)
#存在于此模块中的c文件列表(包括任何子目录)
$(all-c-files)
# list of c files c that exist in dir (including any sub-directories). dir is relative to the module directory
# 存在于dir目录下的c文件列表c(包括所有子目录)。Dir是相对于模块的
$(call all-c-files-in,<dir>)

对于其他支持的文件扩展名请查看 definitions.mak 和 shell.mak 。

外部变量

这些变量可以在命令shell中设置，make 将导入它们。

• NO_OPTIMIZE=1 - disables optimization in the compiler. The target build will be built follow normal debugging flags on this platform.（在编译器中禁用优化。目标构建将遵循此平台上的正常调试标志进行构建。）
• CHECK_MISRA=1 - it enables misra compliance checking however it is compiler dependant（它支持misra遵从性检查，但它依赖于编译器）
• KEEP_ASM=1 - it keeps generated assembly listings however it is compiler dependant（它保持生成的程序集清单，但是它依赖于编译器）
• KEEP_VCC=1 - keep generated VCOP-C code however this is for ARP32/VCOP compiler only（保留生成的VCOP- c代码，但是这只是为ARP32/VCOP编译器）
• BUILD_DEBUG=1 - turns on explicit build output from each command（打开每个命令的显式生成输出）
• TARGET_PLATFORM - indicates the platform to build for (assumes ‘PC’ if not set).（表示要构建的平台(如果没有设置，则假定为“PC”)）
• TARGET_OS = LINUX or Windows_NT or DARWIN or QNX
• TARGET_CPU = ARM or X86 or x86_64 or c64t or c67x
• TARGET_BUILD = debug or release or production - used to generate debuggable components, optimized components or finale builds.
• HOST_OS = LINUX or Windows_NT
• HOST_CPU = X86 or x86_64
• HOST_PLATFORM = PC (ususally)

支持的平台和目标:

Host Environments:（主机环境）

• LINUX
• DARWIN
• WINDOWS (NT or later)
• CYGWIN

Target Environments:（目标环境）

• LINUX
• DARWIN
• WINDOWS (NT or later)
• CYGWIN
• QNX

Target CPUs:（目标CPU架构）

• ARM
• X86
• x86_64
• TI DSPs

Windows版本构建

When building on Windows, you need to install MinGW to get the GNU Make for Windows. Add the path to MinGW’s bin/ folder to your PATH variable. You may want to rename or copy it from mingw32-make.exe to make.exe.
当在Windows上构建时，您需要安装MinGW来获得GNU Make for Windows。将MinGW的 bin/ 文件夹的路径添加到你的PATH变量中。您可能想要将它从 mingw32-make.exe 重命名或复制到 make.exe。

可用的构建系统目标

Concerto 提供了以下有用的规则:

make scrub This will delete the build output directory(这将删除构建输出目录)
make targets Lists all targets defined by concerto.mak files(列出所有通过concerto.mak文件定义的目标)
make <target> This will build the specified target and any of its dependencies（这将构建指定的目标及其任何依赖项）
make <target>_clean Cleans out the specified target（清除指定的目标）
make clean Cleans out all build artifacts for all targets（清除所有目标的所有构建工件）
make vars Outputs the module variables as concerto thinks they are. Useful for debugging.（输出concerto所认为的模块变量。用于调试。）

构建系统的布局

典型的文件夹布局(默认配置)是:

project_folder/

• Makefile
• include/
• source/any depth of folders/concerto.mak
• out/$(TARGET_OS) / $(TARGET_CPU)/ $(TARGET_BUILD)/components

多项目构建:

对于多项目构建，布局只是所有 project_folder 文件夹作为同级在父文件夹，将 out'文件夹作为子文件夹。多项目构建的Makefile只是说明构建的子目录。

DIRECTORIES := someproject/source someproject/docs
DIRECTORIES += otherproject/source otherproject/docs

Concerto 必现仔细以确保没有_MODULES在这两个项目有相同的命名,它改变了_MODULES名字以保证唯一性(否则你会两个组件共享相同的中间对象输出文件夹,你或许遇到编译器和链接器碰撞和非常奇怪的行为)。

---

---

附上源英文README：

What is it?

Concerto is a simple single-pass, non-recursive, full dependency-managed Makefile system.

How it works

Concerto looks for sub-makefiles called concerto.mak in the directories (and their corresponding subdirectories) specified by the DIRECTORIES variable. It will “include” each module’s concerto.mak file into the overall build and resolve all build related macros associated with that module. In this way, it is “single pass” in that all concerto.mak makefiles are read once. The Concerto Build System makefiles like the prelude.mak and finale.mak (and submakefiles therein) are read once per module. These are used to define the make-target macros needed to establish the full depedency tree of the entire build system.

Build System Files:

• definitions.mak - useful macros
• rules.mak - internal top level file.
• os.mak - determines host os
• machine.mak - determines host cpu
• target.mak - determines target variables and build system include paths, variables. This can be replaced (see above).
• scm.mak - tries to extract SCM version information (SVN/GIT)
• prelude.mak and finale.mak - generates non-recursive build system macros and variables per module.
• compilers/* - Compiler specific files
• os/* - OS specific installing/removing rules
• tools/* - tools specific rules.

How to use it

• Download or copy the concerto folder to somewhere on your build system from git clone ssh://$USER@gitorious.design.ti.com:build-systems/concerto.git
• Create a Makefile at the top of you project consisting of the following:

Top Level Makefile per project

# Path to concerto install or use environment variable
CONCERTO_ROOT ?= concerto
# [OPTIONAL] if DIRECTORIES is not specified concerto assumes "source"
DIRECTORIES  := src docs
# [OPTIONAL] BUILD_TARGET is used to reflect specific needs of your build system.
# if not specified concerto's default target.mak is used instead
BUILD_TARGET := $(abspath .)/target.mak
# This calls concerto
include $(CONCERTO_ROOT)/rules.mak

What’s in the concerto.mak

concerto.mak files can contain the following (although it is normally shorter):

_MODULE=<optional module name>
include $(PRELUDE)
TARGET=<name of the object created>
TARGETTYPE=<exe|library|dsmo|prebuilt|jar>
CSOURCES=<list of C files>
CPPSOURCES=<list of C++ files>
ASSEMBLY=<list of .S Files>
KCSOURCES=<list of KernelC .k files>
IDIRS+=<include directories>
DEFS+=<defines>
STATIC_LIBS=<static libraries within the build system>
SHARED_LIBS=<shared libraries within the build system>
SYS_STATIC_LIBS=<static libraries outside the build system>
SYS_SHARED_LIBS=<shared libraries outside the build system>
LINKER_FILES=<list of linker files within the build system>
PREBUILT=<It specifies a single resource to be copied into the target output, only used with the prebuilt TARGETTYPE>
include $(FINALE)

A typical concerto.mak is shorter:

include $(PRELUDE)
TARGET=mytest
TARGETTYPE=exe
SYS_STATIC_LIBS+=sosal
CSOURCES=main.c
include $(FINALE)

Internal Variables

The following variables and macros are available for use in a concerto.mak file.

• _MODULE - the name of the module (if not defined, the containing folder name will be used).
• TARGET - the name of the component to build. Prefixes and postfixes will be added by the build system, do not add them yourself.
• TARGETTYPE - possible values are:

• exe - binary executable
• library - static library
• dsmo - dynamic shared library
• prebuilt - a prebuilt binary
• jar - a Java jar file
• doxygen - A doxygen build
• deb - A debian package (control file is required)

• SYS_SHARED_LIBS - dynamic libraries for which no dependencies are generated (which implies that they are outside the build system).
• SYS_STATIC_LIBS - static libraries for which no dependencies are generated (which implies that they are outside the build system).
• SHARED_LIBS - dynamic libraries for which dependencies are generated (which implies that they are intside the build system).
• STATIC_LIBS - static libraries for which dependencies are generated (which implies that they are inside the build system).
• ASSEMBLY - S files which must be in the same folder.
• CSOURCES - C files which must be in the same folder.
• CPPSOURCES - C++ files which must be in the same folder.
• JSOURCES - Java files for Jar targets
• IDIRS - include directories
• LDIRS - library link path
• DEFS - #defines to pass to the compiler

Useful Macros

# list of files with extension .ext in "dir" and any sub-directory of "dir"
$(call all-type-files-in,<ext>,<dir>)
# list of files with extension .ext that exist inside this module (including any sub-directories)
$(call all-type-files,<ext>)
# list of c files c that exist inside this module (including any sub-directories)
$(all-c-files)
# list of c files c that exist in dir (including any sub-directories). dir is relative to the module directory
$(call all-c-files-in,<dir>)

See definitions.mak and shell.mak for other supported file extensions.

External Variables

The preceding variables can be set in the command shell and make will import them.

• NO_OPTIMIZE=1 - disables optimization in the compiler. The target build will be built follow normal debugging flags on this platform.
• CHECK_MISRA=1 - it enables misra compliance checking however it is compiler dependant
• KEEP_ASM=1 - it keeps generated assembly listings however it is compiler dependant
• KEEP_VCC=1 - keep generated VCOP-C code however this is for ARP32/VCOP compiler only
• BUILD_DEBUG=1 - turns on explicit build output from each command
• TARGET_PLATFORM - indicates the platform to build for (assumes ‘PC’ if not set).
• TARGET_OS = LINUX or Windows_NT or DARWIN or QNX
• TARGET_CPU = ARM or X86 or x86_64 or c64t or c67x
• TARGET_BUILD = debug or release or production - used to generate debuggable components, optimized components or finale builds.
• HOST_OS = LINUX or Windows_NT
• HOST_CPU = X86 or x86_64
• HOST_PLATFORM = PC (ususally)

Supported Platforms and Targets:

Host Environments:

• LINUX
• DARWIN
• WINDOWS (NT or later)
• CYGWIN

Target Environments:

• LINUX
• DARWIN
• WINDOWS (NT or later)
• CYGWIN
• QNX

Target CPUs:

• ARM
• X86
• x86_64
• TI DSPs

Windows Builds

When building on Windows, you need to install MinGW to get the GNU Make for Windows. Add the path to MinGW’s bin/ folder to your PATH variable. You may want to rename or copy it from mingw32-make.exe to make.exe.

Available Build System Targets

Concerto provides the following useful rules:

make scrub This will delete the build output directory
make targets Lists all targets defined by concerto.mak files
make <target> This will build the specified target and any of its dependencies
make <target>_clean Cleans out the specified target
make clean Cleans out all build artifacts for all targets
make vars Outputs the module variables as concerto thinks they are. Useful for debugging.

Build System Layout

The typical folder layout (the default configuration) is:

project_folder/

• Makefile
• include/
• source/any depth of folders/concerto.mak
• out/$(TARGE{T}_{O}S)/$(TARGET_CPU)/$(TARGET_BUILD)/components

Multiproject Builds:

For multiproject builds the layout is just all project_folder folders as peers within a parent folder which will have the out folder as a child. The Makefile for a multiproject build simply notes the subdirs of the build.

DIRECTORIES := someproject/source someproject/docs
DIRECTORIES += otherproject/source otherproject/docs

Concerto has to be careful to make sure no _MODULES are named the same in these two projects, so it alters the _MODULE name to guarentee uniqueness (otherwise you would have two components share the same output folder for intermediate objects and you may be compiler/linker collisions and very odd behavior).