Using a Makefile

Where to obtain it and getting latest documentation

Most projects around here use a Makefile to compile the project into a usable something like a grf file. For NML projects, the recommended Makefile is found in the make-nml project.
For an up to date reference on the capabilities and the configuration see the readme shipped with that project.

Summary

Most makefiles are equipped with three functions:
  • make
  • make install
  • make clean
    additionally the DevZone's NewGRF compiler requires
  • make bundle_zip (binary distribution for players, including license and readme)
  • make bundle_src (source distribution, allowing to re-build the NewGRF from scratch)

make compiles the usable something. make install copies that usable something into a directory that you specify in the Makefile.local file, but more on that later. make clean mostly removes anything that make created. The recommended makefile system is found in the Example newgrf makefile project also found here.

Running a Makefile

You have to run a makefile from the commandline.
  • Open a command prompt and cd to the directory in which the makefile is located that you want to run.
    (Windows Vista users: Use Windows Explorer to browse to the directory, hold shift and then rightclick somewhere inside the file list, choose Open command prompt here)
  • If you just want to compile and nothing else, type the following command and press Enter:
    make
    make && make install
  • The most advanced feature of most makefiles is to compile, install and cleanup all in one go. Run:
    make && make install && make clean

Configuring the makefile: Makefile.config

A makefile is customizable through the Makefile.config which allows to adopt it quickly to a new project

Required settings

Copy the Makefile into the main directory of your NewGRF and create
a Makefile.config which can be copied from the top part of the Makefile.
Makefile.config must contain at least two definitions:

  1. Definition of the grf's name as shown ingame or in the readme
    REPO_NAME = My NewGRF
  1. This is the filename part common to the grf file, main source file and the
  2. tar name
    BASE_FILENAME = mynewgrf

Advanced configuration

Documentation

If you want to ship documentation like readme, changelog or license, you can
and should tell the Makefile about it, so that they're automatically included
into the bundles

DOC_FILES = docs/readme.txt docs/license.txt docs/changelog.txt

NML requirements

If your NewGRF requires a certain NML version or branch you can tell the
Makefile to check for that by means of one or both of the following
definitions:

REQUIRED_NML_BRANCH = 0.3
MIN_NML_REVISION = 2075

Documentation generation

You have the option to automatically replace NewGRF title, filename,
version and grfID by the Makefile, so that it remains current even
when you change them. You can do so, if you call your readme
'readme.ptxt' and have the Makefile generate the readme.txt from it.
Then you have a few special commands in the readme.ptxt which will
be replaced: {{GRF_TITLE}} - this is declared in Makefile.config by REPO_NAME {{REPO_REVISION}} - this is determined by the revision in the mercurial repo
(REPO_REVISION). {{FILENAME}} - this is the grf's filename, e.g. mynewgrf.grf,
automatically generated from the BASE_FILENAME as
declared in Makefile.config

Using DevZone build service

The DevZone checks repositories for the presence of a .devzone directory.
In order to activate building you need to add the files as found in the
make-nml repository. You can choose to not add the nightlies or the releases
sub-directories to disable building of nightly or release builds respectively.
The exact filenames must be retained:
.devzone/build/nightlies/enable
.devzone/build/releases/enable
.devzone/build/type

Using gimp to export layers as png

You need to add to your repository the gimp script files, the exact
names need to be retained:
scripts/gimp.sed
scripts/gimpscript

Additionally, if not yet declared, you need to add to Makefile.config the
script dir:

SCRIPT_DIR = scripts

Further you need to define one or more files which describe which layers
from xcf or psd files shall be exported into which png files. These files
must be made known to the Makefile with their relative path to Makefile,
e.g:

GFX_SCRIPT_LIST_FILES = gfx/png_source_list.xcf2png

You can list in that line, space separated, as many xcf2png files as you
like. Each must follow a specific format:

  • Lines starting with # are ignored and considered comments
  • Other lines are interpreted as rules on how to generate a single png file
    and have the format

path/to/file.png path/to/source.xcf List Of visible Layer Names Separate By Space

All layers of the xcf or psd file NOT listed explicitly here will be invisible
and not part of the exported png.

Using the Makefile

Usually there's not much which needs to be changed when you obtain the
source. Your friends will usually be
make
make install

Both will build the grf from source, the latter will also try to copy
the grf into your grf folder so that it is available for testing and
use straight away.

A brief overview over all Makefile targets is given here:

all:
This is the default target, if also no parameter is given to
make. It will build the grf file and the documentation and
bunndle them in a convenient tar for distribution

docs:
Build the documentation files (if any)

bundle:
This target will create a directory called "<name>-nightly" and
copy the grf file there and the documentation files, readme.txt,
changelog.txt and license.txt

bundle_zip
This will zip the bundle directory into one zip for distribution

bundle_tar
This will tar the bundle directory into a tar archive for
distribution or upload to bananas

bundle_src
Creates a source bundle

install:
This will create a tar archive (like bundle_tar) and copy it
into the INSTALLDIR as specified in Makefile.local (or the
default dir, if that isn't defined). Don't rely on a good
detection of the default installation directory. It's
especially bound to fail on windows machines.

maintainer-clean
This phony targe cleans everything which can be built by them Makefile.
This can also include files which are part of the repository or which
require specific tools or much time to rebuild (like gimp).

distclean:
This phony target cleans everything from a source bundle which
wasn't shipped.

clean:
This phony target will delete all files which this Makefile will
create

check:
Check the md5sum of the built newgrf against the supplied md5sum
(Intended to be used when building from tar balls; it will fail
if no source bundle was built previously)