marktseng / make-common Goto Github PK

STATUS:

 This project has been *discontinued*!  I found that CMake is better,
 so I'm using that instead.  You should go here now:

  http://www.cmake.org/

SET-UP:

  To use this common make logic you need GNU Make 3.81 and you need to
  place a Makefile in the root of your package as such:

  ######################################################################
  SRC:=$(abspath $(dir $(lastword $(MAKEFILE_LIST))))
  include $(or $(shell make-common),$(error make-common is not on your PATH!))

  ... add your logic here.
  ######################################################################

  If you want to create makefiles in other locations, simply include
  the Makefile in the root of your package as such:

  ######################################################################
  include ../Makefile
  ######################################################################

  The make-common command must be in your PATH to perform a build.
  make-common is a simple shell script that locates bootstrap.mk.

  bootstrap.mk provides the following functionality:

  * Defines BUILD (but can be overridden with environment variable).

  * Sets the default target to be 'default'.

  * Creates 'all', 'test', and 'default' phony targets such that
    'default' depends on 'test' and 'test' depends on 'all'.

  * Defines $(make-common.dir) so you can use the functionality
    provided by this package.

  * Defines $(pwd) macro used for determining the directory of the
    current makefile, but it must be expanded *before* any other
    makefile is included in order for it to work.

  * Defines 'clean' target that `rm -rf` the $(BUILD) directory.

  * Defines how to run `pkg-deploy`.

HOW TO USE IT:

  [1] For each module, create a file module.mk and include it in the
      root Makefile.

  include $(SRC)/module-name/module.mk
  include $(SRC)/other/module-name/module.mk

  [2] In each module.mk include the tools that you want to use.  See
      below for usage on individual tools.

TOOL: C compiler

  _pwd := $(pwd)
  include $(make-common.dir)/tool/cc.mk

  _exe  := $(bin.dir)/hello-world
  _objs := $(call cc.c.to.o,$(addprefix $(SRC)/util/, \
    main.c \
  ))

  all: | $(_exe)
  $(_exe): cc.objs=$(_objs)
  $(_exe): $(_objs)
  [TAB]$(cc.exe.rule)
  
TOOL: copy

  _pwd := $(pwd)
  include $(make-common.dir)/tool/cp.mk

  # Copy everything in some-dir into the bin directory:
  $(call cp.eval,$(_pwd)/some-dir,$(bin.dir))

HOW TO CONSUME BUILD ARTIFACTS:

  ######################################################################
  # TODO: This mechanism doesn't work yet since pkg-deploy does not
  # exist yet.
  ######################################################################

  Simply create a file here:

    $(SRC)/build.config

  This file is in JSON syntax with the following structure:

    {   "deploy": {
            "<path>": [
                {   "package": "<pkg-name>",
                    "view":    [ "<view>", "<view>" ]
                },
                {   "package": "<pkg-name>",
                    "view":    [ "<view>", "<view>" ]
                },
            ]
        }
    }

  Where <path> is a path relative to $(BUILD) directory and each
  element in the list declares a <pkg-name> and set of <view>s that
  you want deployed to <path> before your build is started.  The
  package views are applied in the order declared, and if there are
  any symlink conflicts, the last one wins (warning messages about
  conflicts are printed).

  See L<HOW TO EXPORT BUILD ARTIFACTS> for a full description of what
  a view is.

HOW TO EXPORT BUILD ARTIFACTS:

  Place files in your build output directory as such:

    $(BUILD)/exports/<view>.view

  This file is in JSON format and describes how to deploy using a
  particular <view> of this package.  The JSON file has the following
  data structure:

    {   "dependencies": {
            "<pkg-name>": {
                "view": [ "<view>", "<view>${machine}" ]
            },
            "<pkg-name>": {
                "view": [ "<view>", "<view>" ]
            }
        },
        "map": [
            "path/relative/to/build/directory/foo.txt",
            [ "build/relative/dir/bar.txt", "deploy/relative/dir/bar.txt"],
            "path/with/${variable}/escape-with-$$/fun.txt"
        ],
        "variables": {
            "variable": [ "value1", "value2" ],
            "machine":  [ "i686" ],
        }
    }

  This file lists the set of <pkg-name> <view>s that all consumers of
  this package's view will automatically acquire a transitive
  dependency on.  Note that view names may use a "variable" by
  enclosing the variable name in "${" followed by "}".

  It also lists the set of files that are to be deployed when
  consuming this view in the order they are applied (so if two files
  are listed twice, the last one wins).  If an element in this list is
  an array reference, it must consist of exactly 2 elements.  The
  first element is the path relative to the build directory, and the
  second element is the location it should be deployed to.

  Note that the paths in the map may also contain variable names.  If
  you want a literal dollar sign, you must escape it as such: $$.

  All variables must be declared in the "variables" section, and a
  list of all possible values must be enumerated.  When someone
  consumes this view, by default they will get the first value in the
  list if no variable is specified, or the value provided for the
  variable is not in the set.

  It might sounds silly to define a variable that can only have a
  single value, however it can be useful if you merge several builds
  together (like when you are building the same package on multiple
  platforms or with different environment variables or different
  dependencies).

  By default, the variables are taken from any environment set when
  pkg-deploy is executed.  Note that a special variable PLATFORM is
  automatically set by pkg-deploy if none is defined in the
  environment in which case PLATFORM becomes the platform defined for
  the current computer on which pkg-deploy is executing.