Pyke

Pyke is a python build tool which is designed to be simple to use and configure, which also allows you to use the full power of python in your build scripts.

Installation

To install pyke you need to have a package that supplies easy_install installed (personally I use distribute). Once you have easy_install and a copy of the source code you can install pyke by running the following command from the source:

python setup.py install

Usage

pyke [-h] [-t target [target ...]] [-f file] [-v] [-l] [-c] [-a] [-j] [-d] [-r]

Arguments:

When running pyke all arguments are optional.

• -h, --help show this help message and exit
• -t target [target ...], --targets target [target ...] Targets to build, default target is 'default'
• -f file, --file file The build file to load, default file name is 'build.pyke'
• -v, --version Displays version information
• -l, --list Lists all of the available targets in the build file.
• -a, --all Run build/clean against all targets in the build file.
• -c, --clean Remove all build artifacts generated when the target is built.
• -d, --dependencies Generate and store the dependencies for the source files in the target.
• -r, --rebuild Runs a clean followed by a build on the specified targets.
• -b, --builders List the available builders that can be used.

Pyke File

A pyke build file for all intents and purposes is a python script, anything you can do in a python script can be done in a pyke script. A build (including pre & post build methods) are run from the directory that the build file is located in which will be referred to as the base path in this section.

Targets

A target in Pyke is a python method which returns a dictionary object, this object is used to decide what and how to build the target, the values that will be acted upon are as follows:

• source_paths This can either be a string or an array of strings, this field is used to specify the folders where your source code is located. It is important to note that pyke recurses through the directories listed. If no value is supplied then the base path will be used.
• source_patterns This can either be a string or an array of strings, this field is used for matching what files should be compiled, the glob syntax is used to match the files.
• output_path This can only be a string, this field is used to specify the directory where the output files will be compiled to, if no value is supplied then the base path will be used. If this directory does not exist then it will be created.
• output_name This can only be a string, this field is used to specify the name (sans extension) of the executable that will be generated by building the target. If no value is specified then the name of the base path will be used.
• compiler_flags This can be a string or an array of strings, this field contains a list of flags to pass to the compiler.
• linker_flags This can be a string or an array of strings, this field contains a list of flags to pass to the linker.
• compiler This is an optional string which tells pyke what compiler to use, currently the only supported compiler is 'g++'.
• output_type This tells pyke what sort of object to generate, the available options are 'executable', 'staticlib' and 'dynamiclib' if no output_type is specified then it will default to 'executable'.
• dependencies This is an array of strings which list the targets that this target is dependent on to build successfully.
• is_phoney When this is specified all other fields except run and dependencies are ignored, and none of the regular build functionality will be run. Pre & Post build functionality will be run and any dependencies of the target will be run.
• run This field is only referenced when this specifies the method to run between the pre & post build steps.

When no target name is specified in the command line Pyke will try and run a target called default so it is always handy to have one of your targets named default.

Pre & Post Builds

The pre and post build functionality are again just python functions that are called at the appropriate times, they should take no parameters and any returns will be ignored. The pre & post build functionality follows the naming convention of pre builds are the target name with the prefix pre_ and post builds are the target name with the prefix post_ so the pre-build function for the default target would be pre_default and the for the post-build post_default

Cleaning

Pyke has a basic built in clean target which deletes any artifacts generated during the build. This can happen in a couple of ways when using the built-in functionality Pyke will delete the directory specified in the output_path variable from the dictionary generated from the target unless that directory is the same as the base path, in that case pyke will only delete the file that is specified in the output_name variable. If you are not happy with how the default clean functionality works you can override it by specifying a clean function in the build file. Clean functions follow the same naming convention as the pre & post build functions do with the prefix for clean functions being clean_. It is important to note that regardless of which method of cleaning you use the intermediate files generated by the build which are stored in the .pyke directory of the base path will be deleted.

Overwriting Conventions

There may be times when it is useful for multiple targets to share clean, pre & post build functions, or you may just not like the convention that pyke uses in either case you are able to overwrite what functions are called with ones of your choosing. To overwrite those functions you can specify the function or the names of the function in one of the following variables in the dictionary returned from the target.

• prebuild To overwrite the targets pre-build function.
• postbuild To overwrite the targets post-build function.
• clean To overwrite the targets clean function.

Example Build File

Below is a trivial example of a imaginary project that links to two libraries.

def pre_default():
	print('Running the pre-build')

def default():
	return {
		'output_path': 'bin',
		'output_name': 'example_name',
		'source_path': [ 'src' ],
		'source_patterns': [ '*.cc', '*.cpp' ],
		'compiler_flags': [ '-WALL', '-I', '..\\libs\\include' ],
		'linker_flags': [ 'L', '..\\libs', '-lexample-lib-a', '-lexample-lib-b' ]
	}

def post_default():
	print('Running the post-build')

Dependencies

Pyke currently has very naive dependency checking/generation, this is not done at compile-time and must be run separately. The results from the dependency generation are stored in the .pyke file, an example of running the dependency generation is as follows:

pyke --dependencies

For C++ projects the dependency generator will only go two layers deep, it will extract the local headers in the source files and any other local headers those first headers may contain.

To Do

The following is the list of features that are to be incorporated into Pyke and the approximate order in which they will be done.

• Expand to other compilers.
• Add a plugin system to allow others to write builders for compilers.
• Add the ability to embed the compile and link steps in the build file itself.

License

Pyke is available under the MIT license which is as follows:

Copyright © 2013 Michael Lowen

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.