6.5. Convenient path functions

There are some functions that you are encouraged to use when referencing paths, like pyke.masterpath() and pyke.workpath(), which return absolute paths relative to the master pyke file or the current pyke script.

On the other hand, absolutize() is used internally by almost all builtin functions in order to make sure that all paths are absolutized when calling build() function. Knowing about this function might be useful if you plan to create your own rules, otherwise, using pyke.masterpath() and pyke.workpath() will be enough.

pyke.masterpath([path = None])

Returns the absolute path from given path to master path.

When a list is given, returns a list with all its path members absolutized from master path.


>>> masterpath ()

>>> masterpath ('path/')

>>> masterpath (['whatever/inc', 'src'])
['/abs/path/to/project/whatever/inc', '/abs/path/to/project/src']
pyke.workpath([path = None])

Returns the absolute path for the build file being executed, or the absolute file after joining current path.

If given parameter is a list, it will return a list of all the internal paths absolute to current workpath.

Please note that absolute paths will remain unchanged.


>>> workpath ()

>>> workpath ('path')

>>> workpath (['inc', 'src'])
['/abs/path/to/project/current/dir/inc', '/abs/path/to/project/current/dir/src']

>>> workpath ('/abs/path')
pyke.build.absolutize(files, abspath=None, return_list=False, normalize_dirs=False)

Returns the absolute path string to the file or set of files using given absolute path or assuming a path from current working directory.

Please note that virtual files are already absolutized

When a single file is passed as a string, a string is returned When a list of files is passed, a list of files is returned When normalize_dirs is True, it will check if the resulting file is a directory in the current filesystem. This is usually useful when normalizing commands that might accept dirs as input


Returns True if the file calling this function is the pyke masterfile. This can be a useful function to be used when combining multiple independent projects together, so the pyke-rules are loaded only when the subproject is ran independently.

>>> if isMasterFile():
>>>   importRules ('myrules.py')
>>>   include (['required-component'])

Returns the relative route from master path to given path

This function is usually called when generating brief outputs on pyke, to avoid showing long paths.


When no parameter is passed, it returns the absolute path where pyke is installed. If a file is passed, it joins given path to pyke path.

6.6. Basic file rules

This section describes pyke’s builtin file system common operations. Think of them as a multi-platform replacement for common operating system operations.

pyke.rules.mkdir(dirs, mode=511, ignore_errors=False, **kwargs)

Adds a job for creating each directory passed in the dirs list.

dirs can be a path string or list of path strings to specify which directories should be created.
A list with all the directories that should have been created after all dirs exist


>>> mkdir( '/abspath/to/folder' )

>>> mkdir( 'relpath/to/folder' )

>>> mkdir( ['folder1', 'folder2'] )
['/abs/path/to/folder1', '/abs/path/to/folder2']

>>> mkdir( masterpath( ['folder1', 'folder2'] ) )
['/abs/path/to/master/folder1', '/abs/path/to/master/folder2']
pyke.rules.rmdir(paths, ignore_errors=True, **kwargs)

Creates the rules to remove given paths or set of pathss ignore_errors cause this function to always succeed.

e.g: rmdir (path_to_dir, _needs=files_inside)

pyke.rules.cp(sources, target, mkdirs=True, replace=None, overwrite=True, copy_metadata=False, ignore_errors=False, **kwargs)

Copies a one or more source files to given destination

It accepts many sources but only one destination, so you can only copy one file to another file, or several files to a folder.

If the target is a folder that does not exists and mkdirs is True, the folder will get created to be able to copy the files. If mkdirs is False, it will fail.

If the target file exists it will fail, unless ignore_errors is specified in which case it will be overwritten.

pyke.rules.cptree(sources, target=None, overwrite=True, copy_metadata=False, ignore_errors=False, exclude=None, replace=None, **kwargs)

Copies a one or more source files to given destination

It accepts many sources but only one destination, so you can only copy one file to another file, or several files to a folder.

By default this method will overwrite files unless overwrite = False, in which case if a target file exists, it will fail.

exclude can be a path, a file pattern, a list combining both or a regular expression. Please note that exclude = ‘**.txt’ excludes all ‘txt’ files in any folder, whereas ‘.txt’ will probably do nothing, and os.path.join (source, ‘.txt’) will exclude all txt files in the source folder, but will not affect txt files in any of the subfolders being copied. This behaviour is on pourpose.

replace allows to perform internal string replacements on ALL files being copied.


>>> # recursive copy all files from in_folder to out_folder excluding '*.pyc' and '*.bak'
>>> cptree ('in_folder', 'out_folder', exclude = ['**.pyc', '**.bak'])
pyke.rules.clean(files, recursive=False, ignore_errors=True, **kwargs)

This method schedules some files and/or folder to be removed when the ‘clean’ phase is executed.

This is a special method that has been created with the pourpose of being functionally equivalent to the following code:

>>> old_section = pyke.build.section ('clean')
>>> rm (files)
>>> pyke.build.section (old_section)

Here this method works exactly as ‘rm’ with all the parameters, but all methods will be scheduled only in the clean phase, otherwise they will be ignored.

pyke.rules.rm(files, recursive=False, ignore_errors=True, **kwargs)

Creates the rules to remove given set of files

pyke.rules.rmtree(files, ignore_errors=True, **kwargs)
pyke.rules.chmod(*args, **kwargs)

Changes the access flags of an existing file or set of files

pyke.rules.touch(files, **kwargs)

Creates the rules to touch given set of files

Return Value: This method returns all the files that have been created

pyke.rules.putfile(*args, **kwargs)

Creates a file with given string contents

  • ignore_errors: if True, the command will succeed even if a disk error occurs

  • format: ‘text’ to write contents as it is

    ‘json’ to write contents as a json file

Return Value:
This file returns the job node that has been created for the task
pyke.rules.fileappend(file, contents, ignore_errors=False, **kwargs)

Appends given contents to a file, and when the file does not exist, it creates it

  • ignore_errors: ignored
Return Value:
This file returns the job node that has been created for the task
pyke.rules.filereplace(source, target, replace_pairs, ignore_errors=False, force=False, **kwargs)

Opens given filename and replace the contents by using given replacement dictionary.

replace_pairs can be either a dict or a list of tuples where the first item is the search string and the second is the replacement string. Please note that using dicts does not guarantee the replacement order. Also note that compiled regular expressions can be used as well.

NOTE: The whole file is readed in memory for doing replacement


>>> filereplace ('source', 'target', )
pyke.rules.concatfiles(*args, **kwargs)

Creates target file by concatenating all the contents of the source files

pyke.rules.download(*args, **kwargs)

Creates target_file after downloading source_url contents


>>> download ('index.html', 'http://www.google.com/')

6.7. Compression rules

Thanks to python, Pyke has builtin support to compress and uncompress zip, tar, tar.gz and tar.bz2 files. This section describes the compression and uncompression functions.

pyke.rules.makezip(tarfile, sources, recursive=True, exclude=None, verbose=False, ignore_errors=False, **kwargs)

Adds given set of source files inside ‘ziopfile’

pyke.rules.maketar(tarfile, sources, recursive=True, exclude=None, verbose=False, ignore_errors=False, **kwargs)

Adds given set of source files inside ‘tarfile’

pyke.rules.compress(target, sources, algorithm=None, recursive=True, exclude=None, verbose=False, ignore_errors=False, **kwargs)

Compress the source files inside the target file, using appropriate compression algorithm based on the extension.

Depending on the file extension it will use one comperssion or another. .zip -> compress using zip file format .tar -> plain tar with no compression .tgz -> tar+gz .tar.gz -> tar+gz .tar.bz2-> tar+bzip2


>>> pyke.rules.compress ('out.tgz', { 'src/**' : 'tgz-path/src/' })
>>> pyke.rules.compress ('out.tgz', { 'LICENSE' : ['LICENSE', 'COPYING'] })
pyke.rules.unzip(zipfile, target_path, verbose=True, ignore_errors=False, **kwargs)


Not implemented yet!

pyke.rules.untar(tarfile, target_path, verbose=True, ignore_errors=False, **kwargs)


Not implemented yet!

pyke.rules.uncompress(*args, **kwargs)

Exctracts all files inside compressed_file to given taret_dir.

This method supports zip, tar, tar.gz, tgz, tar.bz2 compression formats.

You use filter patterns to include/exclude which files will be uncompressed. There is no way to change the relative location in which files will be created.

6.8. Functions to get depencencies

There are currently a couple of functions that can be used by some rules to build C/C++ and Java projects.

Please note that these are python functions not rules.

pyke.useful.findCppDependencies(cfile, search_paths=None, explicit_deps=None, processed=None)

Open given C/C++ file and analyze all the dependencies C/C++ dependencies (include files) by analyzing #include files

search_paths: list of paths where we can find included files explicit_deps: list of dependencies which might have been created by previous commands

This method uses the internal cache of the files in the current graph for faster lookups


Parse given input java file in order to deduce what would be the names of the output files generated by the ‘javac’ program Usually is the same javafile, unless it contains internal classes or interfaces in which case, new files will be created.

Table Of Contents

Previous topic

6.4. Variables

Next topic

6.9. Working with large projects

This Page