Also, the following goals were explicitly excluded from this build system re-write:
The first approach provides a streamlined building procedure, but requires careful tag, branch, and module management of the Mentok system in the source repository to make sure that modifications propagated back to the Mentok repository from the needs of components do not break features or usage semantics of Mentok needed by other components. This approach places a higher burden on release engineering and the maintainers of Mentok to be careful in making changes, but is very easy on individual component developers. Due to realities of source code management on site, we do not employ this approach at this time.
The 2nd approach has less of a problem with Mentok modification collisions since an external publishing mechanism is expected to version or date-stamp static snap snots of Mentok, but burdens the component using Mentok with a Mentok "bootstrapping" before the normal build process can be performed in the given component tree. The component repository and the "import/dist" mechanisms provided by the "component" Mentok module (documented below) provide a convenient mechanism for managing the Mentok repository in this manor at the bootstrapping cost of what amounts to a recursive copy command that must be executed after component check out and prior to normal component development builds. To make this process easier, a boiler plate component tree with basic Mentok configuration files and code to bootstrap the Mentok system from a component repository with a layout consistent with the tools provided by the "Component" Mentok module is provided in the "build3/bootstrap" directory of any already bootstrapped component or copy of Mentok in the component repository. See the "Component" Mentok module's documentation for details on the component repository and related pattern targets.
Regardless of which method is used to attach a given version of Mentok to a component tree, the layout of a component tree should be fairly uniform. The following component tree layout encompasses both the strict requirements of the Mentok system, and serves as a reference to what is considered to be "best practices" by the developers of Mentok. Use of the terms "MUST", "MUST NOT", "SHOULD", and "SHOULD NOT" are to be interpreted as they are in IETF RFCs.
Path Description <Component root> Top level directory of a component's source tree. This directory path MUST be assigned to the macro "COMPONENT_ROOT" by all leaf Makefiles. <Component root>/build3 The directory in which the Mentok system should be installed for use by the component. This directory path MUST be assigned to the macro "BS_ROOT" by all leaf Makefiles. The name "build3" and location directly under the <Component root> are not strict requirements of Mentok, but represent standard and historical convention. Component developers should not have to modify the contents of this directory. In component trees where Mentok is attached via a bootstrapping mechanism external to the component's source code repository, this directory MUST NOT be checked into the components source code repository. In these cases it is considered a best practice to tell your source code revision control system to ignore this directory. (e.g.: If you are using CVS to manage <Component root>, you can add an entry to <Component root>/.cvsignore to ignore this directory.)
<Component root>/Makefile Top level Makefile. For the most part this Makefile behaves exactly as any other leave Makefile in the component tree, and can specify pattern targets, recursion directories, custom rules etc. By convention all import targets for a component are handled in this makefile. By further (and somewhat vestigial) convention the details of import targets are not directly defined in this Makefile, but specified in a separate imports.mk file that is included into this Makefile.
Components that require a bootstrapping of Mentok can also include custom rules in this Makefile to facilitate auto-bootstrapping by taking advantage of some of the features of gnu make. Examples of such rules are included in the "build3/bootstrap/Makefile" boiler plate.
<Component root>/imports.mk File that includes the definitions of IMPORT_ARCH_TARGETS and IMPORT_NOARCH_TARGETS that is included by <Component root>/Makefile. There is no strict requirement for these pattern targets to be specified in a stand alone file, and simply represents vestigial conventions inherited from Build System 1.0. See the "Component" Mentok module's documentation for details on import targets.
<Component root>/Makefile-build3.mk A stand alone Makefile that does not use the Mentok system at all, but rather provides simple "all" and "clean" targets to bootstrap Mentok in component trees that require this step. This Makefile is intentionally small and simplistic, and is not considered part of Mentok proper since bootstrapping is considered an extra-Mentok activity that is forced onto some component trees by a particular source code control environment. Even so, this file is included in the boiler plate component tree as reference Mentok bootstrapping code. This file is not required in component trees that do not require a bootstrapping step. In components that do require a bootstrapping step it is merely considered a best practice to include this small makefile to accomplish it. Other bootstrapping means may be more appropriate in some environments.
<Component root>/build3-config Directory for all per-component configuration of Mentok. This directory MUST be located directly under the <Component root> and MUST be named "build3-config". <Component root>/build3-config/build3-bootsrap.mk Configuration file used by the <Component root>/Makefile-build3.mk bootstrapping code in the boiler plate component tree. Code outside the bootstrapping process MUST NOT depend on this file. As bootstrapping is considered an extra-Mentok activity, this file is only required in component trees that require a bootstrapping step and use the boiler plate bootstrapping code in <Component root>/Makefile-build3.mk to accomplish it. <Component root>/build3-config/defines.mk Component wide configuration file. Mentok includes make definitions from this file or any file this file includes before evaluating any pattern rules in leaf Makefiles throughout the whole component tree. This is the expected location for a component to globally override Mentok defaults such as compiler flags, default build attributes such as optimization of native code, etc. This is also the appropriate location for a component to define named build variants which can be build concurrently on a given platform via component defined controls leveraging the functionally implied by the "Base" module's "BS_VTAG" control macro. For example, a component could use the macro "MY_COMPONENT_VARIANT" to select different Mentok configurations, and set the "BS_VTAG" to permit these variant to coexist in a developer's component tree.
The following sample <Component root>/build3-config/defines.mk should give you an idea of how much the behavior of the core Mentok modules can be controlled with a few lines of make code.
# Component wide defines file FLAGS_CC += -I$(call COMPONENT_FUNC_IMPORT_COMPUTE_TARGETDIR,some_component_name)/include -I$(COMPONENT_ROOT)/include -D_MY_DEFINE # Force all exe's built in this component to link in a given object by default. FLAGS_LD_EXE_LOADLIBS +=$(COMPONENT_ROOT)/buildnum/$(BS_ARCH_TARGET_DIR)/buildnum.o # # Set build flavor flags bases on VARIANT macro. # It is expected that "VARIANT=foo" will just be tacked onto # your command line invocation of make. # ifeq ($(VARIANT),DEBUG) # # Variant to add debug symbols to code (compiler -g flag) # BS_VTAG = DEBUG NC_CONTROL_DEBUG = 1 else ifeq ($(VARIANT),MY_PROJECT_DEBUG) # # Variant to enable per-project c flags. # BS_VTAG = DEBUG_CODE_ENABLED NC_CONTROL_DEBUG = 1 FLAGS_CC += -DENABLE_MY_PROJECT_DEBUG_CODE else ifeq ($(VARIANT),PURIFY) # # Variant to enable memory debugging - override the default tool chain. # BS_VTAG = PURIFY NC_CONTROL_DEBUG = 1 NC_CONTROL_TOOLCHAIN = PURIFY else # # Default / Release variant. # #BS_VTAG = RELEASE NC_CONTROL_DEBUG = 0 NC_CONTROL_STRIP = 1 NC_CONTROL_OPTIMIZE = 1 FLAGS_CC += -DNDEBUG endif endif endif # # Layer in per-product per-OS defines... # -include $(COMPONENT_ROOT)/build3-config/defines-$(BS_PLATFORM_ARCH_FALLBACK_4).mk -include $(COMPONENT_ROOT)/build3-config/defines-$(BS_PLATFORM_ARCH_FALLBACK_3).mk -include $(COMPONENT_ROOT)/build3-config/defines-$(BS_PLATFORM_ARCH_FALLBACK_2).mk -include $(COMPONENT_ROOT)/build3-config/defines-$(BS_PLATFORM_ARCH_FALLBACK_1).mk -include $(COMPONENT_ROOT)/build3-config/defines-$(BS_PLATFORM_ARCH_FULL).mk # # Layer in build system modules not provided by the base build system. # This demonstrates how far the build system can be extended and configured. # -include $(COMPONENT_ROOT)/build3-config/b3-blackbird/defines-blackbird.mk<Component root>/build3-config/rules.mk Component wide configuration file. Mentok includes make rules from this file or any file this file includes before evaluating any pattern rules in leaf Makefiles throughout the whole component tree. This is the expected location for a component to layer in rules from custom Mentok modules that may not be available by default. The following is a typical example of a i><Component root>/build3-config/rules.mk file: # # Component wide rules file # # # Layer in build system modules not provided by the base build system. # -include $(COMPONENT_ROOT)/build3-config/b3-blackbird/rules-blackbird.mk<Component root>/components* Top level directory for components imported by the import pattern targets provided by the "Component" Mentok module. See the "Component" Mentok module's documentation for more details. It is considered a best practice to tell your source code revision control system to ignore this directory. (e.g.: If you are using CVS to manage <Component root>, you can add an entry to <Component root>/.cvsignore to ignore this directory.)
<Component root>/package* Top level directory for packaging and staging of build targets as packaged by the pattern targets provided by the "Packaging" Mentok module. See the "Packaging" Mentok module's documentation for more details. It is considered a best practice to tell your source code revision control system to ignore this directory. (e.g.: If you are using CVS to manage <Component root>, you can add an entry to <Component root>/.cvsignore to ignore this directory.)
Say something about builds system copy management, and the divorcing of the build dir from the component dir, and how this impacts configuration and usage of the build system.
Say something about overall build process, targets, phases/slices, variants, attributes, and the distinction between these ideas.
Say something about simple targets
Say something about pattern targets
say something about flag targets and dependencies.
Say something about writing and providing modules to extend the build system, include a word on the chicken and egg problem of importing additional modules, and ways around it.