{"id":28176768,"url":"https://github.com/omercsp/simple-build-system","last_synced_at":"2025-10-16T14:29:26.769Z","repository":{"id":65688521,"uuid":"325998516","full_name":"omercsp/simple-build-system","owner":"omercsp","description":"Easy to use and configure C/C++ build system based on Gnu Make","archived":false,"fork":false,"pushed_at":"2025-05-02T11:33:12.000Z","size":212,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-02T12:38:50.288Z","etag":null,"topics":["build","build-system","build-tool","c","clang","cpp","cxx","gcc","gmake","linux","make","makefile","sbs","system","toolchain"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omercsp.png","metadata":{"files":{"readme":"readme.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-01-01T14:52:51.000Z","updated_at":"2025-04-13T10:35:47.000Z","dependencies_parsed_at":"2023-02-18T17:16:01.935Z","dependency_job_id":"d0ed2a75-8a69-4a27-9c8a-d006aea1c778","html_url":"https://github.com/omercsp/simple-build-system","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omercsp%2Fsimple-build-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omercsp%2Fsimple-build-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omercsp%2Fsimple-build-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omercsp%2Fsimple-build-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omercsp","download_url":"https://codeload.github.com/omercsp/simple-build-system/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254443096,"owners_count":22071948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build","build-system","build-tool","c","clang","cpp","cxx","gcc","gmake","linux","make","makefile","sbs","system","toolchain"],"created_at":"2025-05-16T00:19:48.581Z","updated_at":"2025-10-16T14:29:21.714Z","avatar_url":"https://github.com/omercsp.png","language":"Makefile","readme":"[![Sanity](https://github.com/omercsp/simple-build-system/actions/workflows/sanity.yml/badge.svg?branch=master)](https://github.com/omercsp/simple-build-system/actions/workflows/sanity.yml)\n\n# Simple build system\nSBS is a lightweight build system for C/C++ projects using GNU make and either GNU compilers (gcc/g++) or LLVM compilers (clang/clang++). It is intended for users who want an easy-to-install and easy-to-configure build system that doesn't require the user to write complex makefiles, has minimal dependencies and doesn't add steps to the build process. SBS strives for simplicity and ease of use, making most of the build settings a matter of simple configuration, sparing the coder the need to write Makefile rules and, for the most part, even to understand how Makefiles work.\n\nPartial list of SBS features:\n- Simple compilation and linking settings\n- Build flavors (Debug/Release)\n- Automatic setup of source files dependencies\n- Multi-folder project support, with full control over build order\n- Separation of source and build outputs\n\n# Table of Contents\n  - [Target systems](#target-systems)\n  - [Dependencies](#dependencies)\n  - [Installation](#installation)\n  - [Quick start example](#quick-start-example)\n  - [SBS basics](#sbs-basics)\n    - [Modules](#modules)\n    - [Build output and artifacts](#build-output-and-artifacts)\n  - [Build configuration](#build-configuration)\n    - [Name](#name)\n    - [Binary artifact type](#binary-artifact-type)\n      - [Executable](#executable)\n      - [Shared library](#shared-library)\n      - [Static library](#static-library)\n      - [None](#none)\n    - [Source files](#source-files)\n      - [White space in source names and paths](#white-space-in-source-names-and-paths)\n    - [Build flavors](#build-flavors)\n      - [SBS internal flavors](#sbs-internal-flavors)\n    - [Build output](#build-output)\n    - [Compilers suite](#compilers-suite)\n    - [Source file suffixes](#source-file-suffixes)\n    - [Linker](#linker)\n    - [Compilation settings](#compilation-settings)\n      - [Headers search path (include directories)](#headers-search-path-include-directories)\n      - [Preprocessor definitions](#preprocessor-definitions)\n      - [Compiler warnings](#compiler-warnings)\n      - [Pthread support](#pthread-support)\n      - [Header dependencies](#header-dependencies)\n      - [Overriding all compilation flags](#overriding-all-compilation-flags)\n    - [Link settings](#link-settings)\n      - [Linking with other libraries](#linking-with-other-libraries)\n      - [Libraries search path](#libraries-search-path)\n      - [Overriding all link flags](#overriding-all-link-flags)\n  - [Sub-modules](#sub-modules)\n    - [Sub-modules build order](#sub-modules-build-order)\n    - [Example](#example)\n  - [Invocation and Makefiles naming](#invocation-and-makefiles-naming)\n  - [SBS debugging](#sbs-debugging)\n    - [Variables dump](#variables-dump)\n    - [Verbose output](#verbose-output)\n  - [Misc](#misc)\n    - [Pre-build and post-build steps](#pre-build-and-post-build-steps)\n    - [Inclusion of `module.inc.mk` in a complex project structure](#inclusion-of-moduleincmk-in-a-complex-project-structure)\n\n\n# Target systems\nSBS was built specifically for Linux, which is the only platform on which SBS is verified for. However, although not officially supported, SBS is likely useable in any GNU based system.\n\n# Dependencies\nSBS assumes GNU Make and either the GCC or Clang suite are installed.It also relies on Bash but does not require any additional packages or tools.\n\n# Installation\nUsing SBS requires copying a single file: `module.inc.mk`. From that point, it's a matter of configuring the build by writing simple Makefiles.\n\n# Quick start example\nIn a folder named `project`, create a file named `main.c`. Here's a small example for you to paste:\n```c\n#include \u003cstdio.h\u003e\n#include \u003cstdlib.h\u003e\n\nint main(int argc, char **argv)\n{\n        printf(\"Simple-Build-System hello world!\\n\");\n        return EXIT_SUCCESS;\n}\n```\nPlace the `module.inc.mk` file in the `project` folder.\n\nNow it's time to tell SBS what to build and how. In order to do so, add a `Makefile` file to the same directory. Don't worry, it's going to be much smaller and much simpler than your usual Makefile. No rules are required, only basic settings to guide SBS. Only 3 lines are needed:\n\n1. The name of the binary we want to build\n2. List of source files to compile and link, in our example, a single source file - `main.c`\n3. Inclusion of the module.inc.mk file placed in the directory during the installation phase.\n\nHere's how such a Makefile will look:\n```makefile\nMODULE_NAME := my_prog\nMODULE_SRCS := main.c\n\ninclude module.inc.mk\n```\nThat's it! The build setup is complete, and you are ready to build the project and run the executable.\n\nFirst, let's build the project by running make. If there are no compilation errors, the output should look something like this:\n```bash\nproject $ make\nBuilding 'my_prog'\nCC\tmain.c\nLD\tmy_prog\nproject $\n```\n\nNow it's a good time to examine what happened in the project directory. Listing its content will reveal some changes:\n```bash\nproject $ tree\n.\n├── main.c\n├── Makefile\n├── module.inc.mk\n└── obj\n    └── dbg\n        ├── main.c.d\n        ├── main.c.o\n        └── my_prog\n\n2 directories, 6 files\n```\n\nA new directory named `obj` was created in the project directory. All binary outputs are placed in that folder, including `my_prog`, the build executable. The additional `dbg` folder indicates a debug flavor was used. This is the default SBS behavior, and can be configured. The `*.d` files in the build output are dependency files, to force source files compilations in case a header dependency has changed. Don't worry if you are unfamiliar with dependency files.\n\nTo run your program, invoke `obj/dbg/my_prog` from the project directory:\n\n```\nproject $ obj/dbg/my_prog\nSimple-Build-System hello world!\nproject $\n```\n\nAnd that concludes the very basic usage of SBS.\nBrowse the SBS git repository test folder for more advanced examples.\n\n# SBS basics\n## Modules\nIn SBS terms, a module is a group of source files built by the same Makefile and (possibly) linked to a single binary referred to as an artifact. At its most simple and common form, a module contains source files residing in a single folder with a SBS Makefile. More complicated setups can place source files in multiple folders. Each module can have sub-modules to be build before, during and after the module build, as well as pre/post build steps.\n\n## Build output and artifacts\nA build produces object files, dependency files and linked binaries. Usually, the user is mainly concerned about the latter. SBS refers to binary outputs as `artifacts`.\n\n# Build configuration\nFor a basic to intermediate use of SBS, no Makefile rules are needed and almost all SBS settings are defined using a GNU make `\u003cSETTING\u003e := \u003cVALUE\u003e` syntax, so it is better to think of SBS Makefiles as configuration files rather than traditional Makefiles.\n\nThere are quite a few settings, allowing the user to control many aspects of the build. Guidelines and most common configuration settings are covered below. **For a full list of possible settings and their documentation, see the [Makefile.skel](Makefile.skel) file**.\n\nFollowing the module's settings, the Makefile must include (using `include`) the `module.inc.mk` file. It is important the inclusion directive is *after* the modules' settings.\n\nA minimal SBS Makefile will look like this:\n\n```makefile\ninclude module.inc.mk\n```\n\nThough such a Makefile will do absolutely nothing.\nA somewhat more advanced SBS Makefile might look like this:\n\n````makefile\ninclude ../config.mk\n\nMODULE_NAME := mylibrary\nMODULE_BIN_TYPE := shared\nMODULE_SRCS := file1.c file2.c file3.c file4.c\nMODULE_CDEFS += MY_DEF=10\nMODULE_POST_SUB_MODULES := mylibrary_tester\nMODULE_VERBOSE := 1\nMODULE_ARTIFACT_DIR := /path/to/another/folder\n\ninclude ../module.inc.mk\n````\n\nMost of these settings are optional and used for specific needs. In the Makefile above example, the line `MODULE_CDEFS += MY_DEF=10` adds a pre-processor definition of `MY_DEF=10` to the build through a `-DMY_DEF=10` flag. The `MODULE_POST_SUB_MODULES := dynlib_tester` line defines that once this Makefile (module) is built, a `make -C dynlib_tester` is invoked.\n\nInternally, SBS defines variables and make targets prefixed with `sbs` and `SBS`. When writing SBS makefiles, these prefixes should be avoided, as they might get overridden.\n\nSBS defines many variables upon the inclusion of `module.inc.mk`, all can be used *after* the include directive. For example, `SBS_OBJS` lists all the module's object files. There are many such variables, which might be useful in some cases. To see all the internal variables, use `make sbs_dump_internals`. See the [debugging](#sbs-debugging) section for more details.\n\n---\n**NOTE**\n\nSome configuration settings details might look intimidating for the less experienced users. Yet for most of the configuration tasks, just getting them to work should be easy enough, even without understanding exactly what happens under the hood, so don't fret.\n\n---\n\n## Name\nThe module's name serves as the base name for the module linked output name. It is configured with the `MODULE_NAME` setting. The module's name is used for output. With no name set, SBS uses the directory base-name as the module name. So a nameless module that reside in `/dir0/dir1/dir2` will have the name `dir2`.\n\n## Binary artifact type\nA module type defines the artifact type the build produces. SBS module supports 4 kinds of types: executables, dynamic libraries, static libraries and none. The build type is controlled with `MODULE_BIN_TYPE`.\n\n### Executable\nFor an `exec` `MODULE_BIN_TYPE` value, SBS builds an executable. This is the default value if `MODULE_BIN_TYPE` is not set. `exec` binary type doesn't modify any build flags.\n\n### Shared library\nFor a `shared` `MODULE_BIN_TYPE` value, SBS builds a shared library, where:\n- Artifact file name is set to `lib\u003cMODULE_NAME\u003e.so`\n- Compilation flags are appended with `-fPIC`\n- Link flags are appended with `-shared`\n\nRefer to the selected build suite documentation for further details.\n\n### Static library\nFor a `static` `MODULE_BIN_TYPE` value, SBS builds a static library, where:\n- Artifact file name is set to `lib\u003cMODULE_NAME\u003e.a`\n- Link command is `ar` based - `ar -rsc`.\n\nRefer to `ar` documentation for further details.\n\n### None\nFor a `none` `MODULE_BIN_TYPE` value, SBS doesn't build any artifact. It compiles all the source files in the `MODULE_SRCS` list, but does not link them. This module type setting doesn't affect any build flags.\n\n## Source files\nA module's source files are defined with `MODULE_SRCS`. It's a space separated list of files to be compiled. All source files must have a valid C or C++ suffix (e.g. `c`, `C`, `cpp`, `cxx`, etc.). See the [source file suffixes](#source-file-suffixes) section for more details about source files suffixes.\n\nSource files can reside anywhere. Their corresponding object files are always created inside the module's own `obj` directory, so a source file can be compiled multiple times by different modules, possibly with different compilation flags, and different objects will be created on each module.\n\n### White space in source names and paths\nDue to GNU Make limitations, SBS doesn't support source files with names or paths that contain white spaces.\n\n## Build flavors\nFlavors are used to distinguish between different builds and their corresponding artifacts. Flavors are defined with `MODULE_FLAV` setting. With the exception of [SBS internal flavors](#sbs-internal-flavors), flavors only determine the module output directory. For a `MODULE_FLAV := myflav` entry, SBS will use `obj/myflav`, relative to the module directory, as the output directory. It is up to the user to put meaning into the flavor using different build options, and distinguishing it from other flavors.\n\nAll SBS modules must have a flavor. If no flavor is set, SBS defaults to the `dbg` flavor (see below).\n\n---\n**NOTE**\n\nThe idea of flavors, or 'build configurations', as they are called in other build systems, isn't unique to SBS and it is beyond the scope of this guide to explain how to manage them. Common approaches can be based on different project config files for each flavor controlled by renames or soft links, or a common config file branching internally according to an environment variable. To get things started, SBS default internal flavors should be sufficient for most cases.\n\n---\n\n### SBS internal flavors\nSBS provides two internal flavors for debug and release. If the user sets the flavor type to either `dbg` or `rel` SBS will slightly modify the compilation flags with popular relevant settings:\n- Debug (`dbg`) - `-g -O0 -DDEBUG=1 -D__DEBUG__=1`\n- Release (`rel`) - `-O3`\n\nIf you are unfamiliar with these compile options and their meaning, refer the compiler's documentation.\n\nTo prevent SBS from adding any default flags to the build options (e.g., if you want full control over optimization levels), set `MODULE_USE_DEF_FLAV` to `0`.\n\n## Build output\nA module build outputs up to 3 types of files\n\n1. Object files\n2. The target artifact (the executable or library)\n3. Dependency files (See [Header dependencies](#header-dependencies))\n\nBy default, all output files reside in `\u003cMODULE_PATH\u003e/obj/\u003cFLAVOR\u003e`, where flavor is determined by `MODULE_FLAV`. The artifact location can be set to any location by setting `MODULE_ARTIFACT_DIR`. `MODULE_ARTIFACT_DIR` is treated 'as is', and is relative to the current working directory. If it is an absolute path, the absolute path is the artifact directory.\n\nHowever, if `MODULE_ARTIFACT_DIR_REL` is set to `1`, SBS will treat artifact directory set by `MODULE_ARTIFACT_DIR`, as a path relative to the project root directory (i.e. Where `module.inc.mk` resides in). This can be useful for settting a multi module project where binaries are to be placed in single known location, like a project level `lib` directory where other binaries can link with.\n\n## Compilers suite\nSBS supports GCC and Clang as compilers suites. By default, SBS uses GCC (`gcc`) as its compiler suite. To change this behavior, set the `MODULE_CSUITE` setting value to `clang`.\n\n## Source file suffixes\nSBS compiles a given source file as a C or C++ file according to its file extension:\n1. Default C suffixes are `c` and `C`. Modifiable with the `MODULE_C_SUFFIXES` setting.\n2. Default C++ suffixes are `cpp`, `cxx`, `cc`, `CC`, `CXX` and `CPP`. Modifiable with the `MODULE_CXX_SUFFIXES` setting.\n\nSetting either `MODULE_C_SUFFIXES` or `MODULE_CXX_SUFFIXES` overrides the default C or C++ source suffixes. Ensure that all possible C or C++ source file suffixes for the module are included.\n\n## Linker\nBy default, linkage tool is deduced by SBS according to the list of source files: If a C++ file is found among the list of source files, SBS will default to C++ linker, otherwise the C linker is used. Most of the time, allowing SBS to choose the linker will generate the desired behavior, but SBS allows the user to explicitly choose a linker with the `MODULE_LD` setting.\n\n## Compilation settings\nSBS provides a `MODULE_CFLAGS` setting to add any compilation flags. All compilation flags can be controlled with this setting alone. The content of `MODULE_CFLAGS` is appended to any of the module's object compilation command.\n\nSBS also provides dedicated settings for the more common compilation configuration options - header search directories, pre-processor definition, compiler warnings and a few other. These are usually easier to write and maintain than putting all the compilation settings inside `MODULE_CFLAGS` and should generally be preferred over the general `MODULE_CFLAGS`, but it is up to the user to decide how to configure the build. See below for possible dedicated compilation settings.\n\n### Headers search path (include directories)\nSearch path for headers can be appended to the module's compilation commands by setting `MODULE_INCLUDE_DIRS`. It's space separated lists of directories, where each entry `\u003cDIR\u003e` yields a `-I\u003cDIR\u003e` flag in the compilation command.\n\nThe following example yields a `-Isome_dir/include -Iother_dir/include` in the module's objects compile command:\n```makefile\nMODULE_INCLUDE_DIRS := some_dir/include other_dir/include\n```\n### Preprocessor definitions\nPreprocessor definitions can be added to the module's compilation with the `MODULE_CDEFS` setting. It's space separated lists of definitions, where each entry `\u003cDEF\u003e` in the setting yields a `-D\u003cDEF\u003e` flag in the compilation command.\n\nThe following example yields a `-D_GNU_SOURCE -DUSE_LOG=0` in the module's objects compile command:\n```makefile\nMODULE_CDEFS := _GNU_SOURCE USE_LOG=0\n```\n### Compiler warnings\nCompiler warnings are controlled with the `MODULE_CWARNS` setting. It's space separated lists of warnings, where each entry `\u003cWARN\u003e` in the setting yields a `-W\u003cWARN\u003e` flag in the compilation command. So a setting of\n\nThe following setting yields a `-Wno-import -Wformat` in the module's object compile command:\n```makefile\nMODULE_CWARNS := no-import format\n```\n### Pthread support\nGCC and clang provide a specific pthread support using a `-pthread` flag on both compile and link commands. SBS provides a convenience wrapper around this setting with the `MODULE_USE_PTHREAD` setting. Setting it to 1, will add the `-pthread` to the compile and link commands.\n\n### Header dependencies\nBy default, SBS adds compilation flags for header files dependencies generation (`.d`, files) for better build behavior on headers modification. Unchanged, compilation flags are appended with `-MMD -MP`. This behavior can be turned off by setting `MODULE_DEP_FLAGS` value to `0`.\n\nFor more details about headers dependencies generation, consult the compiler's documentation.\n\n### Overriding all compilation flags\nSBS provides a `MODULE_CFLAGS_OVERRIDE` setting to completely override all settings of the compilation, either defined by the user or appended by SBS itself. If you find yourself using this setting extensively, you are probably either misusing SBS or should look for a better suited build system.\n\n## Link settings\nAs with compilation, SBS provides a `MODULE_LDFLAGS` setting to add any flag to the linker. The content of `MODULE_LDFLAGS` is appended to any of the module's link command.\n\nSBS also provides a couple of link flags settings for the more common link configuration options - libraries to link against and library search directories. These are usually easier to write and maintain than putting all the link flags inside `MODULE_LDFLAGS`, and should generally be preferred over the general `MODULE_LDFLAGS`, but it is up to the user to decide how to configure the build. See below for possible dedicated link settings.\n\n### Linking with other libraries\nLibraries to link against can be set with `MODULE_LIBS`. It's space separated lists of libraries, where each entry `\u003cLIB\u003e` yields a `-l\u003cLIB\u003e` flag in the link command.\n\nThe following setting yields a `-lm -luuid` in the module's artifact link command:\n```makefile\nMODULE_LIBS := m uuid\n```\n### Libraries search path\nLibraries search path can be set with `MODULE_LIB_DIRS`. It's space separated lists of directories, where each entry `\u003cDIR\u003e` yields a `-L\u003cDIR\u003e` flag in the link command.\n\nThe following setting yields a `-L/opt/external_project0 -L/opt/external_project1` in the module's artifact link command:\n\n```makefile\nMODULE_LIB_DIRS := /opt/external_project0 /opt/external_project1\n```\n### Overriding all link flags\nA `MODULE_LDFLAGS_OVERRIDE` setting can be used to completely override all linker flags, either defined by the user or those appended by SBS itself.\n\n# Sub-modules\nEach module may define sub-modules. A sub-module is a directory with a valid Makefile in it. It doesn't have to be a SBS module by itself. A sub module can be built before, during or after the parent module. Sub-modules allow complex project folders and build hierarchies. SBS modules might serve as *pseudo* modules, with no sources to compile but with sub modules. Under the hood, sub modules are built by invoking `make -C`. SBS provides settings to define which and when sub modules are built.\n\n`MODULE_SUB_MODULES` - List of folders to be build along the current module.\n`MODULE_PRE_SUB_MODULES` - List of folders to be built before the current module.\n`MODULE_POST_SUB_MODULES` - List of folders to be after before the current module.\n\n## Sub-modules build order\nSub-modules defined by `MODULE_PRE_SUB_MODULES` are built first, followed by the current module. Next, sub-modules in `MODULE_SUB_MODULES` are built, and finally, those in `MODULE_POST_SUB_MODULES` are built.\n\nWhen executing a parallel build (i.e. With `make -j`), the major difference is with the parent module and its sub modules defined in `MODULE_SUB_MODULES`, as they are all built in parallel. Pre and post sub-modules are still built one by one according to the order they are defined (Each sub-module is still built in parallel internally).\n\nTo control the order of sub-modules within `MODULE_SUB_MODULES`, dependencies rules between the sub modules should be explicitly set. For example, if sub modules `sm0 sm1 sm2` are defined but `sm1` must be built before `sm0`, a dependency rule is due:\n\n````makefile\nMODULE_SUB_MODULES := sm0 sm1 sm2\n\nsm0: sm1\n````\n\n## Example\nGiven the following example:\n\n```makefile\nMODULE_SRCS := main.cpp\nMODULE_NAME := my_prog\nMODULE_PRE_SUB_MODULES := pre_order\nMODULE_SUB_MODULES := unordered0 unordered1\nMODULE_POST_SUB_MODULES := post_order\n\ninclude module.inc.mk\n```\n- Running make without parallel build, will build modules in this order:\n1. `pre_order`\n2. `my_prog`\n3. `unordered0`\n4. `unordered0`\n5. `post_order`\n\nRunning make over this Makefile with parallel build will build the current and regular sub-modules in parallel:\n1. `pre_order`\n2. `my_prog` (current module), `unordered0` and `unordered1` are built in parallel\n3. `post_order`\n\n# Invocation and Makefiles naming\nAs a general rule, SBS Makefiles should be simply named `Makefile`, where one Makefile exists in every module directory. Like other GNU-based systems, to run SBS the user should do either of the following:\n1. Enter the module's directory and run `make`\n2. Run `make -C \u003cMODULE_DIR\u003e`.\n\nOccasionally, one might want to have explicit Makefile names in a given directory, where builds are invoked using `make -f \u003cFILENAME\u003e`. SBS offers some support for this type of build command. A SBS Makefile can be named whatever and executed with a `make -f` command, but there are a few notes to consider:\n1. Sub-modules are always built using a default Makefile.\n2. While true for Makefile in general, it's still worth mentioning that more than one Makefile in the same directory (i.e. `Makefile.A` and `Makefile.B`) are hard to maintain and should be carefully written so they won't overwrite one another output. It is usually best avoided.\n\n# SBS debugging\nIn the rare and unheard of case of a buggy build, SBS provides a couple of debugging mechanics:\n## Variables dump\nSBS auto defines a special `sbs_dump_internals` target that shows SBS internal variables generated after the `module.inc.mk` inclusion. This can be used to get some sight into the build process internals.\nAll the variables shown by the `sbs_dump_internals` are available to use (if needed) *after* the inclusion of the `module.inc.mk` file.\n\nSBS also auto defines few targets to summarize the input received from the user (i.e. Defined by the user using `MODULE_\u003cSETTIMG\u003e`):\n1. `sbs_dump_module_vars` - Summary of the module's basic variables\n2. `sbs_dump_module_submodules` - Summary of the module's sub-modules variables\n3. `sbs_dump_module_build_steps` - Summary of the module's build steps (i.e. Pre and post build) variables.\n\nThese targets variants are helpful when working projects where modules makefiles are generated or include other makefiles (as often happens when managing flavors). In the simple case of a self contained module, the target will just echo the module's own variables.\n\nBy default, SBS only dumps non-empty variables. To show all variables regardless of there content, set `SBS_FORCE_DBG` to `1` on invoke. For example on `sbs_dump_module_vars`: `make SBS_FORCE_DBG=1 sbs_dump_module_vars`.\nA target named `sbs_dump_module` combines dump of all module's dump target\nA target named `sbs_dump_all` combines dump of all module's dump target and the SBS internal target.\n## Verbose output\nSetting `MODULE_VERBOSE` to `1` will generate the full build and link commands instead of the easier on the eyes `CC \u003cFILE\u003e` and `LD \u003cFILE\u003e` messages. After setting `MODULE_VERBOSE` to `1` in the quick start example, the output might look like this:\n```bash\nproject $ make clean; make\nCleaning 'my_prog'\nrm -f /home/user/project/obj/dbg/main.c.o /home/user/project/obj/dbg/main.c.d /home/user/project/obj/dbg/my_prog\nBuilding 'my_prog'\ngcc -MMD -MP -g -O0 -DDEBUG=1 -D__DEBUG__=1 -c /home/user/project/main.c -o /home/user/project/obj/dbg/main.c.o\ngcc  -o /home/user/project/obj/dbg/my_prog /home/user/project/obj/dbg/main.c.o\n```\n\n# Misc\n## Pre-build and post-build steps\nSBS defines `MODULE_PRE_BUILD` and `MODULE_POST_BUILD` for actions to be taken before and after a module's build. These settings should refer to valid Make targets. Thus, it requires writing Makefile rules.\n\nThe following example adds a pre-build target that displays a message to the screen at the beginning of the build:\n\n```makefile\nMODULE_PRE_BUILD := display_message\n\ndisplay_message:\n\t@echo \"This is displayed at the beginning of the module's build\"\n```\n\n## Inclusion of `module.inc.mk` in a complex project structure\nSBS cannot determine the location of the `module.inc.mk` file relative to the current module. The user must set this path, and it may differ for each SBS Makefile.\n\nIt's possible to mitigate this problem with external tools. For example, with git, it is a good idea to place the `module.inc.mk` next to the `.git` directory, and use git to determine this location, so the following snippet can be used throughout all the modules within a given project:\n\n```makefile\nPROJ_ROOT=$(shell git rev-parse --show-toplevel)\ninclude $(PROJ_ROOT)/module.inc.mk\n```\nOther tools and environments might provide alternative solutions.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomercsp%2Fsimple-build-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomercsp%2Fsimple-build-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomercsp%2Fsimple-build-system/lists"}