Skip to content

Latest commit

 

History

History
191 lines (150 loc) · 7.53 KB

README.md

File metadata and controls

191 lines (150 loc) · 7.53 KB
Raw

yplatform/build.mk

NOTE this document is not about the internals of make. You can read about that in the GNU make manual, and many other online resources.

But why make??? Because that's why over flowed.

Standardized targets

As early as 2016 someone described why standardization across projects is both possible and important.

No matter which is the primary language, repositories should at all costs implement the following targets:

  • make help to show most important targets, and their description
  • make bootstrap should bootstrap your system with global dependencies
    • example: installing bash/node/python/gnu utils/etc
    • this is not part of the make deps step because it would be innefficient since global dependecies don't change often, take a long time to install, and are also shared to a great extent between our repositories
  • make should always fetch all dependencies, build and run basic checks
    • make should be the same as make all
    • make should be the same as make deps build check
  • make deps should fetch all dependencies
    • no network connection should be required for upcoming make build check
    • dependencies should also be built, where needed
  • make build should build (e.g. compile/transpile/etc)
  • make check should run basic checks (e.g. naming conventions, code style, size of artifacts, run a super quick subset of tests)
  • make test should run the tests (the whole set)
  • make clean should remove all known files to be generated, while leaving behind files that were manually created. This is prone to errors, since the files need to manually listed inside the Makefile.
  • make nuke or make clobber should remove all unknown files to git (untracked files). Internally it actually creates a stash, so you can safely recover a file.

Standardized variables

  • V=1 should trigger a verbose build .e.g V=1 make or make V=1
    • this is perfect for initial debugging

Development workflow

After git clone-ing a repository, a developer should run make bootstrap in order to install global dependencies.

After that, a developer should only need to run make, in order to get a fully functional repository, ready for development.

Similarly, after making changes, a developer should only need to run make in order to explore their changes. Or run make all test in order to check that tests are green.

NOTE the above can be slightly optimized by running the specific tasks alone e.g. make build or make build test, but an unexperienced/occasional developer shouldn't be forced to know about these optimizations.

Beyond knowing just make, for specific tasks, a developer should know only about make help.

Writing Makefiles

In order to follow the standardized targets mentioned above, but also do diminish duplication and errors/corner-cases, we make use of partial Makefiles that when combined cover a great deal of the basic requirements and build steps, while still allowing for customization/extensibility where needed.

Use the Makefile "puzzle" pieces below by making your main Makefile look like this:

ifeq (,$(wildcard yplatform/Makefile))
INSTALL_YP := $(shell git submodule update --init --recursive yplatform)
ifneq (,$(filter undefine,$(.FEATURES)))
undefine INSTALL_YP
endif
endif

include yplatform/build.mk/generic.common.mk
include yplatform/build.mk/...

# ------------------------------------------------------------------------------

... include here custom EXE variables, which call which/npm-which ...

... include here custom variables ...

... include here yplatform variables (configuration) ...

# ------------------------------------------------------------------------------

... include here your custom targets ...

The pieces MUST be included in this order:

  • common (e.g. generic.common.mk)
  • deps
  • build
  • check
  • test
  • release
  • misc

NOTE All are split into:

  • docs
  • includes
  • variables
  • targets

The high-level collections of pieces are as follows:

Miscelaneous "must haves" require generic.common.mk:

Addon pieces by type of repository:

For a full list of available pieces click here.

References