About BuildHelper

I'm sure we've all written scripts to help our build processes. I hope to stop repeatedly inventing this wheel for new projects, and to find some reusability.

To use these tools, either copy BuildHelper into your repository, or reference it as a git submodule. It's up to you.

git clone https://github.com/jeffsw/buildhelper
pip3 install --requirement buildhelper/requirements.txt
mkdir acme/BuildHelper
cp buildhelper/* acme/BuildHelper

VersionHelper Usage

Configure for Your Project

After you've copied BuildHelper into your repo, create a configuration file called VersionHelper.yml that looks like the example, below.

Use the --help option for more details on configuration parameters.

Example VersionHelper.yml configuration (YAML format):

---
# acme/VersionHelper.yml
symbol_prefix: ACME_
touch:
  - src/acme_version.c
c_file: src/acme_version.h
c_template: BuildHelper/c.template

Tag Your Build

Use git tags to identify your project's version numbers.

git tag -a release-1.0 -m "I am declaring this commit to be release 1.0"
git push && git push --tags

Run VersionHelper

Then, simply run the tool:

jsw@athena:~/acme$ BuildHelper/VersionHelper.py
#VersionHelper running on ./
#VersionHelper C BuildHelper/c.template -> src/acme_version.h
#VersionHelper touched src/acme_version.c
#VersionHelper had 2 effects

Or add VersionHelper to your Makefile (or other build system config):

# run VersionHelper before building acme_version.o
src/acme_version.o: src/acme_version.c
    BuildHelper/VersionHelper.py
    $(CC) $(CFLAGS) $(INCLUDES) -c $< -o $@

# always rebuild src/acme_version.o so it stays up to date
.PHONY: src/acme_version.o

Check the Results

Now, we have an updated src/acme_version.h file. If you know C, you'll see this defines several macros and declares some string variables which, when combined with src/acme_version.c, allows other parts of the project to simply refer to those strings.

If you don't want all that, just edit the template c.template to suit your preferences.

#pragma once
#ifndef ACME_VERSION_H
#define ACME_VERSION_H
/**
 * @file This file is generated by VersionHelper.py at build time
 * See also https://github.com/jeffsw/buildhelper/
 */

#define ACME_VERSION_BUILD_HOST "athena"
#define ACME_VERSION_BUILD_TIME "Tue Jan 16 23:59:28 2018"
#define ACME_VERSION_BRANCH "master"
#define ACME_VERSION_COMMIT "6d4b94ebfcf8b8772368e79b0745395137f1724d"
#define ACME_VERSION_DESCRIBE "r1.1"
#define ACME_VERSION_STRING "1.1"

extern const char * acme_version_build_host;
extern const char * acme_version_build_time;
extern const char * acme_version_branch;
extern const char * acme_version_commit;
extern const char * acme_version_describe;
extern const char * acme_version_string;

#endif /* ifndef ACME_VERSION_H */

Tips

Consider adding your output files (like version.h) to your project's .gitignore as you shouldn't want them in your repo; you want those files to arise at build time.

jsw@athena:~/acme$ echo "src/acme_version.h" >> .gitignore

To list all your builds, just run git tag --list.

To check out a previous build, git checkout <tag name>. Don't be surprised if this puts your working directory into detached HEAD state. That's normal!

TODO

Pull requests welcome!

tests
bundled templates for more languages

Send Coins

If this saves you some time, the best thanks are crypto-coins:

Bitcoin bitcoin:1GtKy3S3RFpd4SVGrDVSXDycyNP13i4xmo Etherium 0x82E1B2479f0DED2be4558b7CD36757F566CDd8Ff

License

BuildHelper is made available under the MIT License.

References

PEP 440 http://www.python.org/dev/peps/pep-0440/

jeffsw / buildhelper