| Name | pyke-build JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | A python-based build system for automating build and deployment tasks. |
| upload_time | 2024-05-11 01:21:10 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License |
| keywords |
c
c++
build
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pyke
Pyke is a python-based, extensible system for building and operating software projects. Its first functions centered around cleaning and building C and C++ projects, but it can do much more. Future development work will expand languages and environments in which pyke can be useful, actions such as installing, deploying and testing, and may support a plugin interface for expansion beyond the core.
## The rationale
Pyke is being designed to act initially as an alternative to CMake. I'm no expert in CMake, and many of the below may also apply to it, but I wanted to build pyke as a personal project, and use it in other projects of my own.
- **Minimal artifacts**
Within a project, the only artifacts that result from a build operation are the intermediate files from the build itself (.o files, specifically, for C-family projects) and the final output. The only necessary support file in a project is the make.py file itself, probably at the project root folder.
- **Flexibility**
Of course, the pyke project file doesn't have to be at the root of a project. And it doesn't have to be called make.py. A pyke file can specify specific anchor directories for project files and generated artifacts. Command-line overrides can modify them in times of need.
- **Just-beyond-declarative configuration**
Usually, a declarative syntax is desireable for systems like this. But even CMake is a sort of language, and pyke files are too--just, in python. Very basic python is all you need to know to use it fully, and when you need that convenience of a full language, it's very nice to have. Sane defaults and a simple object structure help keep things fairly minimal for a basic project.
- **Extensibility**
Pyke comes with some basic classes (called `Phase`s) which can manage basic tasks. But you may have special needs in your project tha require a specific tool to be run, or files to be moved around, or secret keys to be managed, etc. If it's not in the basic set of classes, build your own. It's a reasonable interface to design new functionality for.
## Installing pyke
Couldn't be easier. You need to be running python3.10 at least, and have pip installed. To install it globally:
```
$ python3 -m pip install pyke-build
```
or,
```
$ python3 -m pip install --user pyke-build
```
You can optionally put it in a virtual environment, which may be the better idea.
Alternatively, you can clone this repo and install locally:
```
$ git clone https://github.com/spacemeat/pyke
$ cd pyke
$ python3 -m pip install .
```
## Using pyke
We'll do a simple example. We have a C project laid out like this:
```
simple_app
├── include
│ └── abc.h
└── src
├── a.c
├── b.c
├── c.c
└── main.c
```
We want to build each .c file to an object, and link the objects together. Let's make a file called make.py, and place it in the root.
```python
from pyke import CompileAndLinkToExePhase, get_main_phase
phase = CompileAndLinkToExePhase({
'name': 'simple',
'sources': ['a.c', 'b.c', 'c.c', 'main.c'],
})
get_main_phase().depend_on(phase)
```
Now it's as simple as invoking pyke:
```
$ pyke build
```
The project was quietly built in a subdirectory:
```
├── build
│ └── simple_app.gnu.debug
│ ├── bin
│ │ └── simple
│ └── int
│ ├── a.o
│ ├── b.o
│ ├── c.o
│ └── main.o
├── include
│ └── abc.h
├── make.py
└── src
├── a.c
├── b.c
├── c.c
└── main.c
```
where `build/simple_app.gnu.debug/bin/simple` is the final binary executable.
Of course, this is a very minimal example, and much more configuration is possible.
## The `make.py` file
So what's in this `make.py` file? The general execution is to start pyke, and pyke will then find your `make.py` makefile in the current directory (your project root). Pyke will import the makefile, run it, and then begin executing actions based on what your makefile has configured and what you specify on the command line. All `make.py` does, in the simple cases, is add `Phase`-derived objecs to a provided top-level `ProjectPhase` object. Pyke does the rest.
So in the example above, first `make.py` imports the important pyke symbols. Then it sets up a single phase: `CompileAndLinkToExePhase`. In its definiton are two options: `name` and `sources`: the specific C source files. Then this phase is added as a `dependency` to a provided main `ProjectPhase`. That's all pyke needs to know how to build.
Pyke always begins with the phase object (a `ProjectPhase` instance), for the whole project. It can be accessed through `pyke.get_main_phase()`, which returns the phase. The CompileAndLinkToExePhase is then registered to the project via the `depend_on()` method. Pyke will use the phases it's given and the options set to each phase, along with the command line arguments, to perform the needed tasks: In this example, it will make the appropriate directories, invoke gcc or clang with configured arguments (in a POSIX environment), and optionally report its progress.
### So how does pyke know where to find the sources? Or the headers? Or where to put things?
Every `Phase`-derived class defines its own default options, which give a default configuration for its actions. As an example, one option in `CompileAndLinkToExePhase` is `src_dir`, which specifies the directory relative to the project root (actually an achor directory, but mnore on that later) where source files can be located. The default is "src", which also happens to be where simple's source files are stored. Similarly, simple's headers are stored in "include", and `CompileAndLinkToExePhase` has another option named `include_dirs` which contains "[include]". Note that this is a `list` of length one, holding the default directories where include files are to be found. When it comes time to build with, say, `gcc`, the `include_dirs` value becomes "-Iinclude", and the source files are given as source arguments to `gcc`. There is more to the story of how directories are determined, but this suffices for the moment.
Every option can have its default value modified or replaced. If your source files are stored in a different directory (say, "source" instead of "src"), you can add `'src_dir': 'source'` to the phase definition, and pyke will find the files.
> You can also set `src_dir` to "'.'", the dot directory, and explicitly path each source file, like:
> `"'sources': ['src/a.c', 'src/b.c', 'src/c.c', 'src/main.c']"`
> Though, of course, that's just more typing.
### Interpolation, basically
In a nutshell, a string value in an option can have all or part of it enclosed in `{}`. This specifies an interpolation, which is simply to replace that portion of the string with the option given by the name in braces. The name is recursively looked up in the options table for that phase, its string values interpolated the same way, and returned to replace. We'll get into detail and examples below.
> It should be noted that most of these options so far are actually contained in a `Phase`-derived class called `CFamilyBuildPhase`, which `CompileAndLinkToExePhase` derives from. This is because several other `CFamilyBuildPhase`-derived classes make use of the same options. It works just the same, since derived phase class inherit their supers' options.
## Phases
Most phases generally represent the transformation of files--inputs to outputs. Any useful build phase will have input files and output files. Some of these may be source, authored by developers. Some may be created by compiling source to objects, linking objects to executables or libraries, cloning repositories, or running code generation tools. When the outputs of one phase are the inputs of another, the one is a `dependency` of the other. Dependencies are set in the makefile explicitly, and their output->input mechanistry is automatic once set.
Each operation of a build, such as the compilation of a single source file, may have a dedicated phase. C/C++ builds that are more complex than "simple" above may have a `CompilePhase` instance dedicated to each single source file->object file transformation, and one for each link operation, etc. Phases can be `cloned`, and their options as set at the time of cloning are copied with them. So, a template `CompilePhase` can be preset, and each clone made have its requisite source file set to `src`. Each `CompilePhase` object would then be set as a dependency of a `LinkToExePhase` object, which will automatically gather the generated object files from each `CompilePhase` for linking. Such an example makefile might look like this (with an additional few source files in a differnt directory, for spice):
```python
'multiphase cloned test'
import pyke as p
c_to_o_phases = []
proto = p.CompilePhase()
for src in ('a.c', 'b.c', 'c.c', 'main.c'):
c_to_o_phases.append(proto.clone({'name': f'compile_{src}', 'sources': [src]}))
proto = p.CompilePhase({
'src_dir': 'exp',
'obj_dir': 'int/exp',
})
for src in ('a.c', 'b.c'):
c_to_o_phases.append(proto.clone({'name': f'compile_exp_{src}', 'sources': [src]}))
o_to_exe_phase = p.LinkToExePhase({
'name': 'link',
'exe_basename': 'simple_1',
}, c_to_o_phases)
p.get_main_phase().depend_on(o_to_exe_phase)
```
Here, we're creating a prototype `CompilePhase` object, and storing clones of it, one for each compile operation, in a list. Those phases become dependencies of the `LinkToExePhase` object, which in turn is set to the main project phase.
### Built-in phases
Pyke comes with some built-in `Phase` classes--not many yet, but it's early still:
* `class Phase`: Common base class for all other phases.
* `class CommandPhase(Phase)`: A generic shell command phase. Often serves as a base class for a custom build step.
* `class CFamilyBuildPhase(Phase)`: Common base class for building C and C++ projects. You won't decleare objecs of this type, but rather subclasses of it, as it does not actually implement many `action`s.
* `class CompilePhase(CFamilyBuildPhase)`: Phase for compiling a single source file to a single object file.
* `class ArchivePhase(CFamilyBuildPhase)`: Phase for building static libraries out of object files.
* `class LinkToSharedObjectPhase(CFamilyBuildPhase)`: Phase for linking objects together to form a shared object (dynamic library).
* `class LinkToExePhase(CFamilyBuildPhase)`: Phase for linking objects together to form an executable binary.
* `class CompileAndArchive(CFamilyBuildPhase)`: Phase for combining compile and archive operations into one phase.
* `class CompileAndLinkToSharedObjectPhase(CFamilyBuildPhase)`: Phase for combining compile and link operations into one phase for building a shared object.
* `class CompileAndLinkToExePhase(CFamilyBuildPhase)`: Phase for combining compile and link operations into one phase for building an executable.
* `class ProjectPhase(Phase)`: Project phase, which represents a full project. You can create multiple projects as dependencies of `get_main_phase()`, each their own subproject with compile and link phases, etc. The top-level phase of a makefile is always a project phase.
An easier view of the class heierarchy:
```
Phase
├── CommandPhase
├── CFamilyBuildPhase
│ ├── CompilePhase
│ ├── ArchivePhase
│ ├── LinkToSharedObjectPhase
│ ├── LinkToExePhase
│ ├── CompileAndArchive
│ ├── CompileAndLinkeToSharedObjectPhase
│ └── CompileAndLinkToExePhase
├── ProjectPhase
```
### Dependencies
As mentioned, dependencies among phases are set in the makefile. There are several things to know about dependency relationships:
* Mostly what dependencies do is generate the files other dependent phases need.
* They cannot be cyclical. The dependency graph must not contain loops, though diamond relationships are fine.
* Option overrides and actions that are specified to multiple phases in a dependency tree happen in reverse depth-first order. The deepest dependency phases act first; this way, dependencies that build objects will happen before those that depend on them to build libraries, etc. When setting actions and overrides from the command line, the default is to set them to all phases, so whole dependency graphs can be levered at once.
If your project has multiple steps to build static libraries or shared objects (dynamic libraries) which are then used by other binaries in the build, you can make them dependencies of the built binary phases that use them. The appropriate directories and file references will automatically be resolved. Further, depnding on the properties of the project, appropriate dynamic lookup options will be inserted as well (like `-rpath` options for UNIX-like systems).
## Actions
Pyke is not just good for building. There are other standard actions it can perform, with more forthcoming. Actually, it's more correct to say that `Phase` objects perform actions. Any string passed as an action on the command line will be applied to the appropriate phases which implement the action. If no phase supports the action, it is quietly ignored.
There is a default action (`report_actions`) which displays the available actions in each phase of a project. This default can be overridden in a config file, either in a project or under $HOME (see [configuring pyke](#configuring-pyke)), to make the default action something different.
### Built-in actions
Currently, the supported actions in each built-in phase are:
|phase class|actions
|---|---
|Phase|clean; clean_build_directory; report_actions; report_files; report_options
|CommandPhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)
|CFamilyBuildPhase|(inherited: clean; clean_build_directory; report_actions; report_files; report_options)
|CompilePhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)
|ArchivePhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)
|LinkToSharedObjectPhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)
|LinkToExePhase|build; run; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)
|CompileAndArchivePhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)
|CompileAndLinkToSharedObjectPhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)
|CompileAndLinkToExePhase|build; run; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)
|ProjectPhase|(inherited: clean; clean_build_directory) (all other actions are the responsiblity of dependencies)
These can be spcified on the command line. Multiple actions can be taken in succession; see below for CLI operation.
* `report_options` prints a report of all phases and their options and overrides. This is useful to check that your command line overrides are doing what you think.
* `report_files` prints a report of the files that are used and generated by each phase.
* `report_actions` prints a report of all the actions each phase will respond to.
* `clean` specifies that a phase will delete the files it is responsible for making.
* `clean_build_directory` specifies that the entire build directory tree will be deleted.
* `build` is the build action. This generates the build artifacts.
* `run` runs built executables in place. Note that CommandPhase commands happen on the `build` action.
### Action aliases
There are built-in aliases for the defined actions, to save some effort:
|alias|actions
|---|---
|opts|report_options
|files|report_files
|actions|report_actions
|c|clean
|cbd|clean_build_directory
|b|build
### Action mapping
You may wish to associate one action to another. For example, an executable that `build` creates may itself be part of a later `build` action, but it can run only on the `run` action. You can wire up an action to be performed on another action by setting a particular `action map` as an option:
```python
doc_builder = p.CompileAndLinkToExePhase({
...
'action_map': { 'build_docs': [ 'build', 'run' ]},
...
})
```
This specifies that, on the `build_docs` action, this phase should run its `do_action_build` method, followed by its `do_action_run` method. This allows for some flexibility in the action set for your makefile, especially if you're using a built-in or 3rd-party phase class.
## Options
Options do not have to be strings. They can be any Python type, really, with the following criteria:
* Options should be *convertible* to strings.
* Options must be copyable (via `copy.deepcopy()`).
We've already seen list-type options, like `sources`, and there are several of those in the built-in phase classes. Custom ANSI colors for output are stored as dictionaries of dictionaries. And of course, any phase class you create can use any new option types you desire, as long as they meet the above criteria.
### Overrides are stacked
When an option is applied to a phase which already has as option by the same name, it is called an `override`. The new option displaces or modifies the existing one, but it does not replace it internally. Rather, it is pushed onto the option's *stack* of values, and can later be *popped* to undo the modification. In this way, an override can, say, remove an entry from an option's listed elements, and later popping of that override will bring it back.
### Override operators
So how does one specify that an override *modifies* an option, instead of *replacing* it? When specifying the name of the option to set with `-o`, you can provide '+=' or '-=' or another operator to specify the modifier. A few option types get special behavior for this syntax:
|original type|operator|override type|effect
|---|---|---|---
|any|=, none|any|the option is replaced by the override
|bool|!= |bool|logical negation of the boolean value
|int\|float|+=, -=, *=, /=|int\|float|performs standard math operations
|string|+= |any|appends str(override) to the end of the string
|string|-= |string|removes the first instance of the override string from the string
|list|+= |any|the override is appended to the list
|list|*= |list\|tuple|the override elements extend the list
|list|-= |any|the override is removed from the list
|list|\\= |int|the override specifies an index to remove from the list
|list|\\= |list[int]\|tuple[int]\|set[int]|the override specifies a collection of indices to remove from the list
|tuple|+= |any|the override is appended to the tuple
|tuple|*= |list\|tuple|the override elements extend the tuple
|tuple|-= |any|the override is removed from the tuple
|tuple|\\= |int|the override specifies an index to remove from the tuple
|tuple|\\= |list[int]\|tuple[int]\|set[int]|the override specifies a collection of indices to remove from the list
|set|+=, \|=|any non-set|the override is added to the set
|set|-= |any|the override is removed from the set
|set|\|= |set|the result is unioned with the set
|set|&= |set|the result is intersected with the set
|set|\\= |set|the result is the difference with the set
|set|^= |set|the result is the symmetric difference with the set
|dict|+= |dict|the result is the union with the dict
|dict|-= |any|the entry is removed from the dict by key
|dict|\|= |dict|the result is the union with the dict
We'll see some examples below.
### Viewing options
The base `Phase` class defines the `report_options` action, with an alias of `opts`. This action prints the phases in depth-first dependency order, and each phase's full set of options in both raw, uninterpolated form, and fully interpolated form. This makes it easy to see what options are available, the type each is set to by default, and how interpolation and override operations are affecting the final result. It's handy for debugging a difficult build.
```
$ pyke opts
name =
= compile_and_link
= simple
-> simple
group =
= simple_app
-> simple_app
report_verbosity: = 2
-> 2
report_relative_paths: = True
-> True
verbosity: = 0
-> 0
none: = None
-> None
true: = True
-> True
false: = False
-> False
project_anchor: = /home/schrock/src/pyke/tests/simple_app
-> /home/schrock/src/pyke/tests/simple_app
gen_anchor: = /home/schrock/src/pyke/tests/simple_app
-> /home/schrock/src/pyke/tests/simple_app
...
```
Each option is listed with all its stacked raw values, followed by the interpolated value. Notice above that the default value of "verbosity" is set to 0. This makes build actions behave without output (unless there is an error). We can easily see how command-line overrides affect the results. More on how to set them below, but overriding the `verbosity` option with `2` looks like this:
```
$ pyke -o verbosity=2 opts
...
verbosity: = 0
= 2
-> 2
...
```
Here, `verbosity` has been overridden, and has a second value on its stack. Subsequent actions will report more information based on the verbosity value.
The detailed report from `report_options` (`opts`) is what you get at `report_verbosity` level `2`. If you want to see only the interpolated values, you can override the `report_verbosity` option to `1`:
```
$ pyke -o report_verbosity=1
name: -> simple
group: ->
report_verbosity: -> 1
report_relative_paths: -> True
verbosity: -> 0
project_anchor: -> /home/schrock/src/pyke/demos/simple_app
gen_anchor: -> /home/schrock/src/pyke/demos/simple_app
...
```
Like actions, there are argument aliases for some options. `-v2` sets the verbosity to 2, and `-rv1` sets the report_verbosity to 1. There are others as well.
### Interpolation
The details on interpolation are straighforward. They mostly just work how you might expect. A portion of a string value surrounded by `{}` may contain a name, and that name is then used to get the option by that name. The option is converted to a string, if it isn't already (it probably is), and replaces the substring and braces inline, as previously explained. This means that interpolating an option which is a list will expand that list into the string:
```
$ pyke -o formatted_list_of_srcs="'Sources: {sources}'" opts
...
formatted_list_of_sources: = Sources: {sources}
-> Sources: ['a.c', 'b.c', 'c.c', 'main.c']
...
```
If the entire value of an option is interpolated, rather than a substring, then the value is replaced entirely by the referenced option, and retains the replacement's type. This is useful for selecting a data structure by name, as explained below.
#### Nested interpolated strings
One useful feature is that interpolations can be nested. `CFamilyBuildPhase` uses this in places to help resolve selectable options. Look carefully at `kind_optimization`'s raw value below. It contains four `{}` sets, two inside the outer, and one nested even deeper. The inner set is interpolated first, and then the outer set according to the new value.
```
$ pyke report
...
kind: = debug
-> debug
...
tool_args_gnu: = gnuclang
-> gnuclang
tool_args_clang: = gnuclang
-> gnuclang
...
gnuclang_debug_optimization: = 0
-> 0
...
gnuclang_release_optimization: = 2
-> 2
...
optimization: = {{tool_args_{toolkit}}_{kind}_optimization}
-> 2
...
```
So `optimization` evolves as:
```
optimization: -> {{tool_args_{toolkit}}_{kind}_optimization}
-> {{tool_args_gnu}_{kind}_optimization}
-> {gnuclang_{kind}_optimization}
-> {gnuclang_debug_optimization}
-> 0
```
Now, when overriding `kind`, a different version of the optimization flags (passed as `-On` to gcc, say) will be automatically interpolated:
```
$ pyke -o kind=release opts
...
kind: = debug
= release
-> release
...
optimization: = {{tool_args_{toolkit}}_{kind}_optimization}
-> 2
...
```
### Overriding in the makefile
When constructing phase objects, the options you declare are technically overrides, if they happen to have the same name as any inherited options. They are treated by default as replacements, though you can provide operators.
You can also explicitly override after phase creation:
```python
from pyke import CompileAndLinkToExePhase, Op, get_main_phase
phase = CompileAndLinkToExePhase('simple_experiemtal', {
'sources': ['a.cpp', 'b.cpp', 'c.cpp', 'main.cpp'],
'include_dirs': Op('+=', 'include/exp') # appending to include_dirs
})
phase.push_opts({
'sources': Op('*=', [f'exp/{src}' for src in [ # extending sources
'try_this.cpp', 'maybe.cpp', 'what_if.cpp']])
})
get_main_phase().depend_on(phase)
```
Note the use of the `Op` class, which signals that the override is an operational modifier, not merely a replacement. The operator is expressed as a string. Overriding with a value directly instead of with `Op` implies a replacement ('=').
> Note the difference between *appending* one item to a list with `+=`, as in the phase constructor above, and *extending* multiple items to the list with `*=`, as in the push_opts() call.
You can pop the override with `Phase.pop_opts(key)`.
> `Phase.push_opts` is defined on `Phase` as:
> ```python def push_opts(self, overrides: dict, include_deps: bool = False, include_project_deps: bool = False) ```
> The boolean parameters tell pyke how to propagate overrides through dependency phases. `include_deps` includes dependencies which are not `ProjectPhase`s, and `include_project_deps` includes only `ProjectPhase` phases specifically. Options set in `Phase` constructors call `push_opts` with both set to `False`.
### Overriding on the command line
As seen previously, overrides can be specified on the command line as well with `-o [phases:][option[op value]`. This can look similar to overrides in code (though you may need to enquote it):
```
$ pyke -ocolors=none build
$ pyke -o "compile:sources *= [exp/try_this.c, exp/maybe.c, exp/what_if.c]" opts
```
String values can be in quotes if they need to be disambiguated from punctuation or shell interpolation. The usual escapements work with '\\'. Overrides you specify with `[]` are treated as lists, `()` as tuples, `{}` as sets, and `{:}` as dicts. Since option keys must only contain letters, numbers, and underscores, you can differentiate a single-valued set from an interpolation by inserting a comma, or specifically enquoting the string:
```
$ pyke -o "my_set_of_one={foo,}" ...
$ pyke -o "my_set_of_one={'foo'}" ...
```
Python's built-in literals True, False, and None are defined as options, and can be interpolated as {true}, {false}, and {none}.
Much like older-style subshell invocation, you can enquote a shell command in \`backtick\`s, and the command will be executed, with its output inserted in place. This is most useful in config files, since they're not executed in a shell context.
There is more to say about how value overrides are parsed. Smartly using quotes, commas, or spaces to differentiate strings from interpolators will usually get you where you want. Generally, though, setting options in the makefile will probably be preferred.
### Base pyke options
There are a few options that are uiversal to pyke, regardless of the type of project it is running. Here are the options you can set to adjust its behavior:
|option|default|usage
|---|---|---
|name |'' |The name of the phase. You should likely override this.
|group |'' |The group name of the phase. Informed by its nearest dependent project phase.
|report_verbosity |2 |The verbosity of reporting. 0 just reports the phase by name; 1 reports the phase's interpolated options; 2 reports the raw and interpolated options.
|report_relative_paths |True |Whether to print full paths, or relative to $CWD when reporting.
|verbosity |0 |The verbosity of non-reporting actions. 0 is silent, unless there are errors; 1 is an abbreviated report; 2 is a full report with all commands run.
|none |None |Interpolated value for None.
|true |True |Interpolated value for True.
|false |False |Interpolated value for False.
|project_anchor |project_root |This is an anchor directory for other directories to relate to when referencing required project inputs like source files.
|gen_anchor |project_root |This is an anchor directory for other directories to relate to when referencing generated build artifacts like object files or executables.
|build_dir |'build' |Top-level build directory.
|colors_24bit |color_table_ansi_24bit |24-bit ANSI color table.
|colors_8bit |color_table_ansi_8bit |8-bit ANSI color table.
|colors_named |color_table_ansi_named |Named ANSI color table.
|colors_none |color_table_none |Color table for no ANSI color codes.
|colors_dict |'{colors_{colors}}' |Color table accessor based on {colors}.
|colors |supported_terminal_colors |Color table selector. 24bit|8bit|named|none
|action_map |{} |Routes action invocations to action calls.
|toolkit |'gnu' |Select the system build tools. gnu|clang
|kind |'debug' |Sets debug or release build. You can add your own; see the README.
|version_major |'0' |Project version major value
|version_minor |'0' |Project version minor value
|version_patch |'0' |Project version patch value
|version_build |'0' |Project version build value
|version |'{version_mmp}' |Dotted-values version string.
When running pyke from a directory that is different from your makefile's directory, you can specify the makefile path with `-m`. This is discussed below, but by default both the project root directory (`project_anchor`) and generated output root directory (`gen_anchor`) are relative to the makefile's directory, regardless of where you invoke from. However, this behavior can be modified. By overriding `gen_anchor` to a different directory in your file system, you can cause all the generated outputs to be placed anywhere. The generated directory structure remains the same, just at a different root location. Note that intermediate files which are inputs of later phases, like compiled object files, are still resolved correctly, as *any* generated file is rooted by `gen_anchor`. Likewise, any file that is expected as part of the project inputs created by developers (anything you might check in to your project repository, say) is anchored by `project_anchor`.
If you don't want your makefile to be situated at the project root, overriding `project_anchor` (possibly in the makefile itself) to the actual project root will line things up.
### C/C++ specific options
Pyke began as a build tool for C and C++ style projects. The requisite classes are those that derive from `CFamilyBuildPhase`, and have lots of options for controlling the build. Note that since clang and gcc share much of the same command arguments, their toolchain-specific arguemts are often combined into a single definition.
|option|default|usage
|---|---|---
|language |'c++' |Sets the source language. c|c++
|language_version |'23' |Sets the source language version.
|gnuclang_warnings |['all', 'extra', 'error'] |Sets the warning flags for gnu and clang tools.
|gnuclang_debug_debug_level |'2' |Sets the debug level (-gn flga) for gnu and clang tools when in debug mode.
|gnuclang_debug_optimization |'g' |Sets the optimization level (-On flag) for gnu and clang tools when in debug mode.
|gnuclang_debug_flags |['-fno-inline', '-fno-lto', '-DDEBUG'] |Sets debug mode-specific flags for gnu and clang tools.
|gnuclang_release_debug_level |'0' |Sets the debug level (-gn flga) for gnu and clang tools when in release mode.
|gnuclang_release_optimization |'2' |Sets the optimization level (-On flag) for gnu and clang tools when in release mode.
|gnuclang_release_flags |['-DNDEBUG'] |Sets release mode-specific flags for gnu and clang tools.
|gnuclang_additional_flags |[] |Any additional compiler flags for gnu and clang tools.
|definitions |[] |Macro definitions passed to the preprocessor.
|posix_threads |False |Enables multithreaded builds for gnu and clang tools.
|relocatable_code |False |Whether to make the code position-independent (-fPIC for gnu and clang tools).
|rpath_deps |True |Whether to reference dependency shared objects with -rpath.
|moveable_binaries |True |Whether to condition the build for dependencies which can be relatively placed. (-rpath=$ORIGIN)
|include_dirs |['include'] |List of directories to search for project headers, relative to {include_anchor}.
|sources |[] |List of source files relative to {src_anchor}.
|lib_dirs |[] |List of directories to search for library archives or shared objects.
|libs |{} |Collection of library archives or shared objects or pkg-configs to link. Format is: { 'foo', type } where type is 'archive' | 'shared_object' | 'package'
|prebuilt_obj_dir |'prebuilt_obj' |Specifies the directory where prebuilt objects (say from a binary distribution) are found.
|prebuilt_objs |[] |List of prebuilt objects to link against.
|build_detail |'{group}.{toolkit}.{kind}' |Target-specific build directory.
|obj_dir |'int' |Directory where intermediate artifacts like objects are placed.
|obj_basename |'' |The base filename of a taret object file.
|posix_obj_file |'{obj_basename}.o' |How object files are named on a POSIX system.
|thin_archive |False |Whether to build a 'thin' archive. (See ar(1).)
|archive_dir |'lib' |Where to emplace archive library artifacts.
|archive_basename |'{name}' |The base filename of a target archive file.
|posix_archive_file |'lib{archive_basename}.a' |How archives are named on a POSIX system.
|rpath |{} |Collection of library search paths built into the target binary. Formatted like: { 'directory': True } Where the boolean value specifies whether to use $ORIGIN. See the -rpath option in the gnu and clang tools. Note that this is automatically managed for dependency library builds.
|shared_object_dir |'lib' |Where to emplace shared object artifacts.
|shared_object_basename |'{name}' |The base filename of a shared object file.
|generate_versioned_sonames |False |Whether to place the version number into the artifact, and create the standard soft links.
|so_major |'{version_major}' |Shared object major version number.
|so_minor |'{version_minor}' |Shared object minor version number.
|so_patch |'{version_patch}' |Shared object patch version number.
|posix_so_linker_name |'lib{shared_object_basename}.so' |How shared objects are unversioned-naemd on POSIX systems.
|posix_so_soname |'{posix_so_linker_name}.{so_major}' |How shared objects are major-version-only named on POSIX systems.
|posix_so_real_name |'{posix_so_soname}.{so_minor}.{so_patch}' |How shared objects are full-version named on POSIX systems.
|posix_shared_object_file |'{posix_so_linker_name}' |The actual target name for a shared object. May be redefined for some project types.
|exe_dir |'bin' |Where to emplace executable artifacts.
|exe_basename |'{name}' |The base filename of a target executable file.
|posix_exe_file |'{exe_basename}' |How executable files are named on POSIX systems.
|run_args |'' |Arguments to pass when running a built executable.
### Making sense of the directory optinos
Each of the include, source, object, archive, static_object and executable directories are built from components, some of which you can change to easily modify the path. Pyke is opinionated on its default directory structure, but you can set it how you like.
#### Include files
```
inc_dir = .
include_anchor = {project_anchor}/{inc_dir}/\<include directory\>
include_dirs = [include]
```
You are encouraged to change `inc_dir` to set a base directory for all include directories. Pyke will reference `include_anchor` and `include_dirs` directly when building command lines; `inc_dir` is just there to construct the path.
#### Source files
```
src_dir = src
src_anchor = {project_anchor}/{src_dir}
```
You are encouraged to change `src_dir` to set a base directory for all the source files. Note that there is only a single source directory specified. Pyke does not search for named files; rather, you need to explicitly specify each source's directory or path.
#### Build base directory structure
```
build_dir = build
build_detail = {kind}.{toolkit}
build_anchor = {gen_anchor}/{build_dir}
build_detail_anchor = {build_anchor}/{build_detail}
```
You are encouraged to change `build_dir` to set a different base for generated files, and `build_detail` to control different buld trees. Pyke will reference `build_detail_anchor` and `build_dir` directly.
#### Intermediate (object) files
```
obj_dir = int
obj_basename = \<source_basename\> (named after either a source file or the phase name, depending on `intermediate_build` and the phase type)
obj_file = {obj_basename}.o (.obj on Windows)
obj_anchor = {build_detail_anchor}/{obj_dir}
obj_path = {obj_anchor}/{obj_file}
```
You are encouranged to change `obj_dir` to set a base directory for intermediate files. Pyke will only reference `obj_path` directly, and will override `obj_basename` for each source file.
#### Binary (executable) files
```
exe_dir = bin
exe_basename = {name}
exe_file = {exe_basename} (with .exe on Windows)
exe_anchor = {build_detail_anchor}/{exe_dir}
exe_path = {exe_anchor}/{exe_file}
```
You are encouraged to change `exe_dir` to set a base directory for executable files, and `exe_basename` to set the name of the executable. Pyke will only reference `exe_path` directly.
Similar options are defined for static archives and shared objects. Of course, you can change any of these, or make your own constructed paths.
### Recursive makefiles
You can run another makefile within a makefile:
```python
# shaper/libs/make.py:
import pyke as p
shape_lib = p.CompileAndLinkToArchive()
s = shape_lib.clone({'name': 'sphere', 'sources': ['shapes/sphere.cpp']})
c = shape_lib.clone({'name': 'cube', 'sources': ['shapes/cube.cpp']})
i = shape_lib.clone({'name': 'icosohedron', 'sources': ['shapes/icosohedron.cpp']})
p.get_main_phase().depend_on([s, c, i])
```
```python
# shaper/exe/make.py:
import pyke as p
base = p.run_makefile('../libs') # tries to load '../libs/make.py'
libs = [base.find_dep(lib) for lib in ('sphere', 'cube', 'icosohedron')]
exe = p.CompileAndLinkToExePhase({'sources': ['main.c']}, libs)
p.get_main_phase().depend_on(exe)
```
Here, the makefile `../libs/make.py` is run. Its ProjectPhase is returned as `base`, and the phases it loaded can be found in its dependency tree. The `project_anchor` and `gen_anchor` options are preserved for each makefile, though you can change them manually. Each makefile will also load its cohabiting `pyke-config.json` file as well, unless you suppress it with a parameter:
```python
...
base = p.run_makefile('../libs', False) # does not load libs/pyke-config.py, even if it exists.
...
```
## The CLI
The general form of a pyke command is:
```
pyke [-v | -h | [-c]? [-m makefile]? ]? [[-p [phase[,phase]*]]* | [-o [phase[,phase]*:]key[op_value]]* | [phase[,phase]*:][action]* ]*
```
Notably, -o and action arguments are processed in command-line order. You can set the phases to use with each, setting some option overrides, performing actions, setting different options, perform more actions, etc. If no phases are specified, the overrides and actions apply to all phases, in reverse depth-first dependency order.
The command line arguments are:
* `-v`, `--version`: Prints the version information for pyke, and exits.
* `-h`, `--help`: Prints a help document.
* `-m`, `--makefile`: Specifies the module (pyke file), or its directory if the pyke file is called 'make.py', to be run. Must precede any arguments that are not -v, -h, or -c. If no -m argument is given, pyke will look for and run ./make.py.
* `-n`, `--noconfig`: Specifies that the `pyke-config.json` file adjacent to the makefile should not be loaded.
* `-c`, `--report-config`: Prints the full combined configuration from all loaded config files, and exits.
* `-p`, `--phases`: Specifies a subset of phases on which to apply subsequent overrides or actions, if such arguments do not provide their own. Each `-p` encountered resets the subgroup. Option and action arguments that provide their own phases overrule `-p` for that argument, but do not reset it.
* `-o`, `--override`: Specifies an option override to apply to some or all phases for subsequenet actions. If the option is given as a key-op-value, the override is pushed; if it is only a key (with no operator-value pair) the override is popped.
* `action`: Arguments given without switches specify actions to be taken on the indicated phases. Any action on any phase which doesn't support it is quietly ignored.
### Referencing phases
Phases have names (`short name`s), as seen, but also have `full name`s, given as "group.name". For each phase, if the group name is not explicitly set, it is overridden *after the makefile is run* to be the short name of the closest dependency *project phase*. Project phases are thereafter given the short name `project`. This naming scheme allows for subprojects to be referenced by the group name on the CLI. We'll see some examples.
The main project group is named according to the name of the makefile, unless it is specifically called `make.py`, in which it is name of the directory in which it resides. So, if your project's root contins the makefile, and is named like this:
```
~/src/asset_converter/make.py
```
The project will be called "asset_converter.project". If, however, it is named like:
```
~/src/asset_converter/images_make.py
```
The project will be called "images_make.project".
Dependency phases of any project phase which are not themselves project phases are specified by the dotted name. Maybe your `asset_converter` project has dependencies like this:
```
asset_converter (ProjectPhase)
├── image_converter (ProjectPhase)
│ └── link (LinkToExePhase)
│ ├── compile_jpg (CompilePhase)
│ ├── compile_png (CompilePhase)
│ └── compile_tga (CompilePhase)
└── mesh_converter (ProjectPhase)
└── link (LinkToExePhase)
├── compile_blender (CompilePhase)
├── compile_3ds (CompilePhase)
└── compile_dxf (CompilePhase)
```
Here, each phase will be fully named by its owning project phase and its non-project phase names:
* `asset_converter.project`
* `image_converter.project`
* `image_converter.link`
* `image_converter.compile_jpg`
* `image_converter.compile_png`
* `image_converter.compile_tga`
* `mesh_converter.project`
* `mesh_converter.link`
* `mesh_converter.compile_blender`
* `mesh_converter.compile_3ds`
* `mesh_converter.compile_dxf`
When referencing phases on the command line, you can always reference by full name. For convenience, you can omit the group name of the main project, and it will be implied. An @ symbol references all the phases in either the group, short name, or both. So, for simple_app, you can reference just the compile phase like:
```
pyke -o compile:verbosity=2
pyke -o .compile:verbosity=2
pyke -o simple_app.compile:verbosity=2
```
By default, if the phase names are not specified at all, then all phases are affected. In actuality, it uses phase name "@.@", and is usually what you'd want. For complicated projects with multiple ProjectPhases, each can be separately referenced precisely.
```
pyke -okind=release -oimage_converter.@:kind=debug build
```
The above performs a release build for most of the project, but a debug build for only the image_converter subproject. If you want to just build image_converter:
```
pyke image_converter.@:build
```
Note that the naming is *not* strictly hierarchical, but rather, specifically `group.name`. Phases must always be uniquely named within a project (and will be automatically disambiguated if they're not).
## Configuring pyke
Pyke has an internal cnofig which provides some convenient aliases. On startup, once pyke has found the makefile but before it is loaded, pyke looks for additional configs in the following order:
* ~/.config/pyke/pyke-config.json
* <makefile's directory>/pyke-config.json
An example config might look like this:
```json
{
"include": ["../pyke-config.json"],
"argument_aliases": {
"-noc": "-ocolors=none",
"-bdb": "dbadmin:build",
"-rdb": [
"-odbadmin:run_args=\"-logging=TRUE -username=$DBADMIN_UNAME -password=$DBADMIN_PASSWD\"",
"dbadmin:run"
]
},
"action_aliases": {
"pf": "package_flatpak",
"vac": "verify_appchecker"
},
"default_action": "build",
"default_arguments": [
"-v2"
],
"cache_makefile_module": "true"
}
```
Each can contain the following sections:
### Include files
These are paths to other JSON files which contribute to the configuration. They are loaded before the rest of this file's contents, which can add to or override as described below. Useful if you have distinct configuration for work projects vs. personal projects, or lots of pyke projects which all use the same options. Paths that start with '/' are absolute; otherwise, they are relative to this file's path.
### Argument aliases
These are convenient shorthands for complex overrides, override-action pairs, or whatever you like. Their values cannot contain other argument alias names, but *can* contain action aliases, and are otherwise exactly as you'd type them on the CLI (except you don't need to enquote things that the shell might interpret). Multiple values must be housed in a list. Each config file adds to the list of argument aliases.
### Action aliases
Actions can be aliased. These are one-for-one word replacements, and the action values must not be other action aliases, though you *can* have more than one alias for any given action. Each config file adds to the list of action aliases.
### Default action
The default action is taken when no action is specified on a CLI. By default, this is set to `report_actions`. The value must not be an alias. Each config file overrides a set default action.
### Default arguments
Ccontains a list of strings, each of which is a separate command line argument. These can be full names or aliases. They are placed consecutively directly after the -m argument, but before any -o or action arguments, on every invocation of pyke. It is a convenient way to customize the way pyke always works on your project or machine. Each config file appends to the list of default arguments.
### Cache makefile module
Allows the makefile's __cache__ to be generated by python. This might speed up complex builds, but they'd hvae to be really complex.
## Advanced Topics
### Adding new phases
Of course, a benefit of a programmatic build system is extension. Building your own Phase classes shold be straightforward. You likely won't have to often.
Say you need a code generator. It must make .c files your project compiles and links with extant source. You can write a custom Phase-derived class to do just this. This gets you into the weeds of `Step` and `Result` classes, and action steps. More help will be provided in the future, but for now, let's just look at the code in demos/custom_phase/custom.py:
```python
''' Custom phase for pyke project.'''
from functools import partial
from pathlib import Path
from pyke import (CFamilyBuildPhase, Action, ResultCode, Step, Result, FileData,
input_path_is_newer, do_shell_command)
class ContrivedCodeGenPhase(CFamilyBuildPhase):
'''
Custom phase class for implementing some new, as-yet unconcieved actions.
'''
def __init__(self, options: dict | None = None, dependencies = None):
super().__init__(options, dependencies)
self.options |= {
'name': 'generate',
'gen_src_dir': '{build_anchor}/gen',
'gen_src_origin': '',
'gen_sources': {},
}
self.options |= (options or {})
def get_generated_source(self):
''' Make the path and content of our generated source. '''
return { Path(f"{self.opt_str('gen_src_dir')}/{src_file}"): src
for src_file, src in self.opt_dict('gen_sources').items() }
def compute_file_operations(self):
''' Implelent this in any phase that uses input files or generates output files.'''
for src_path in self.get_generated_source().keys():
self.record_file_operation(
None,
FileData(src_path.parent, 'dir', self),
'create directory')
self.record_file_operation(
FileData(Path(self.opt_str('gen_src_origin')), 'generator', self),
FileData(src_path, 'source', self),
'generate')
def do_step_generate_source(self, action: Action, depends_on: list[Step] | Step | None,
source_code: str, origin_path: Path, src_path: Path) -> Step:
''' Performs a directory creation operation as an action step. '''
def act(cmd: str, origin_path: Path, src_path: Path):
step_result = ResultCode.SUCCEEDED
step_notes = None
if not src_path.exists() or input_path_is_newer(origin_path, src_path):
res, _, err = do_shell_command(cmd)
if res != 0:
step_result = ResultCode.COMMAND_FAILED
step_notes = err
else:
step_result = ResultCode.SUCCEEDED
else:
step_result = ResultCode.ALREADY_UP_TO_DATE
return Result(step_result, step_notes)
cmd = f'echo "{source_code}" > {src_path}'
step = Step('generate source', depends_on, [origin_path],
[src_path], partial(act, cmd=cmd, origin_path=origin_path, src_path=src_path),
cmd)
action.set_step(step)
return step
def do_action_build(self, action: Action):
''' Generate the source files for the build. '''
def get_source_code(desired_src_path):
for src_path, src in self.get_generated_source().items():
if src_path == desired_src_path:
return src.replace('"', '\\"')
raise RuntimeError('Cannot find the source!')
dirs = {}
all_dirs = [fd.path for fd in self.files.get_output_files('dir')]
for direc in list(dict.fromkeys(all_dirs)):
dirs[direc] = self.do_step_create_directory(action, None, direc)
origin_path = Path(self.opt_str('gen_src_origin') or __file__)
for file_op in self.files.get_operations('generate'):
for out in file_op.output_files:
source_code = get_source_code(out.path)
self.do_step_generate_source(action, dirs[out.path.parent],
source_code, origin_path, out.path)
```
There's a bit going on, but it's not terrible. Actions already implemented in `CFamilyBuildPhase` can clean generated source and the generation directory, as well as make directories for the build. The main work here is in generating the source files in an appropriate generation directory.
Integrating this custom phase into your makefile is as simple as making a new instance of the new phase, and setting it as a dependency of the build phase:
```python
'Bsic project with custom code generation phase'
# pylint: disable=wrong-import-position
from pathlib import Path
import sys
sys.path.append(str(Path(__file__).parent))
from custom import ContrivedCodeGenPhase
import pyke as p
gen_src = {
'd.c': r'''
#include "abc.h"
int d()
{
return 1000;
}''',
'e.c': r'''
#include "abc.h"
int e()
{
return 10000;
}'''
}
gen_phase = ContrivedCodeGenPhase({
'gen_src_origin': __file__,
'gen_sources': gen_src,
})
build_phase = p.CompileAndLinkToExePhase({
'name': 'simple',
'sources': ['a.c', 'b.c', 'c.c', 'main.c'],
}, gen_phase)
p.get_main_phase().depend_on(build_phase)
```
And that's it. Now the `build` action will first generate the files in the right place if needed, and then build them if needed. The `clean` action will delete the generated files, and the `clean_build_directory` action will not only remove the build, but also the generated source directory.
> A few notes: The above will only generate the source files if they don't exist, or are older than the makefile (which has the source text in it). Also, the gen diretory is based on `gen_anchor` (by way of `build_anchor`), which is necessary for any generated files to be built in the right place if you change `gen_anchor`'s value.
#### Adding new actions
To add a new action to a custom phase, simply add a method to the phase class. For example, to add an action called "deploy", write a phase method like so:
```python
...
def do_action_deploy(self, action: Action) -> ResultCode:
...
```
(You'll want to import Action and ResultCode from pyke if you want the annotations.) That's all you need to do for the method to be called on an action, since actions' names are just strings, and pyke reflects on method names to find a phase that can handle the action. Of course, implmenting actions is more involved, as you can see above.
### Adding new build kinds
Adding new build kinds is straightforward if you're just trying to customize the system build commands. There are currently three that depend on the build kind: `debug_level`; `optimization`; and `flags`. For POSIX tools, these correspond to the `-g{debug_level}`, `-O{optimization}`, and `{flags}` of any definition. If you wanted a custom kind called "smallest", simply provide the following overrides, with perhaps these values:
```
'gnuclang_smallest_debug_level': '0',
'gnuclang_smallest_optimization': 's',
'gnuclang_smallest_flags': ['-DNDEBUG'],
```
When selecting the build kind with `-o kind=smallest`, these overrides will be selected for the build.
### Setting colors
The colorful output can be helpful, but not if you're on an incapable terminal, or just don't like them or want them at all. You can select a color palette:
```
pyke -o colors=none build
pyke -o colors=named build
pyke -o colors=8bit build
pyke -o colors=24bit build
```
Defining your own color palette is possible as well. You'll want to define all the named colors:
```
pyke -o colors_custom="{ off: {form:off}, success: {form:b24, fg:[0,255,0], bg:[0,0,0]}, ...}" -o colors=custom build
```
That gets cumbersome. You can change an individual color much more easily:
```
pyke -o "colors_24bit|={shell_cmd: {form:b24, fg:[255, 255, 255]}}"
```
These are likely best set as default arguments in `$HOME/.config/pyke/pyke-config.json`. (See [configuring pyke](#configuring-pyke).):
```json
{
"default_arguments": [
"-o colors_super = { off: { form: off }}",
"-o colors_super |= { success: { form: b24, fg: (0x33, 0xaf, 0x55) }}",
"-o colors_super |= { fail: { form: b24, fg: (0xff, 0x33, 0x33) }}",
"-o colors_super |= { phase_lt: { form: b24, fg: (0x33, 0x33, 0xff) }}",
"-o colors_super |= { phase_dk: { form: b24, fg: (0x23, 0x23, 0x7f) }}",
"-o colors_super |= { step_lt: { form: b24, fg: (0xb3, 0x8f, 0x4f) }}",
"-o colors_super |= { step_dk: { form: b24, fg: (0x93, 0x5f, 0x2f) }}",
"-o colors_super |= { shell_cmd: { form: b24, fg: (0x31, 0x31, 0x32) }}",
"-o colors_super |= { key: { form: b24, fg: (0x9f, 0x9f, 0x9f) }}",
"-o colors_super |= { val_uninterp_lt: { form: b24, fg: (0xaf, 0x23, 0xaf) }}",
"-o colors_super |= { val_uninterp_dk: { form: b24, fg: (0x5f, 0x13, 0x5f) }}",
"-o colors_super |= { val_interp: { form: b24, fg: (0x33, 0x33, 0xff) }}",
"-o colors_super |= { token_type: { form: b24, fg: (0x33, 0xff, 0xff) }}",
"-o colors_super |= { token_value: { form: b24, fg: (0xff, 0x33, 0xff) }}",
"-o colors_super |= { token_depth: { form: b24, fg: (0x33, 0xff, 0x33) }}",
"-o colors_super |= { path_lt: { form: b24, fg: (0x33, 0xaf, 0xaf) }}",
"-o colors_super |= { path_dk: { form: b24, fg: (0x13, 0x5f, 0x8f) }}",
"-o colors_super |= { file_type_lt: { form: b24, fg: (0x63, 0x8f, 0xcf) }}",
"-o colors_super |= { file_type_dk: { form: b24, fg: (0x43, 0x5f, 0x9f) }}",
"-o colors_super |= { action_lt: { form: b24, fg: (0xf3, 0x7f, 0x0f) }}",
"-o colors_super |= { action_dk: { form: b24, fg: (0xa3, 0x4f, 0x00) }}",
"-o colors=super"
]
}
```
The above colors are the default for 24-bit RGB colors. Change them however you like.
An individual color has the format:
```
{form: <format>, fg: <foreground-color>, bg: <background-color>}
```
For b24 formats, each of fg and bg should specify a tuple of red, green, blue, from 0 through 255. For b8 formats, each of fg and bg should specify a single integer [0, 255] which matches the ANSI 8-bit color palette. For the named formats, the ANSI named colors are used, like 'red' and 'bright blue'. If you want to specify no color, leave the color dict empty. The 'off' color dict is special, and must be kept as '{form: off}'.
Raw data
{
"_id": null,
"home_page": null,
"name": "pyke-build",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Trevor Schrock <spacemeat@gmail.com>",
"keywords": "C, C++, build",
"author": null,
"author_email": "Trevor Schrock <spacemeat@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f9/96/23f541d6af32f9ce77e2835f7965117320f6e0f19fac81a11a6022798330/pyke_build-0.2.0.tar.gz",
"platform": null,
"description": "# pyke\n\nPyke is a python-based, extensible system for building and operating software projects. Its first functions centered around cleaning and building C and C++ projects, but it can do much more. Future development work will expand languages and environments in which pyke can be useful, actions such as installing, deploying and testing, and may support a plugin interface for expansion beyond the core.\n\n## The rationale\n\nPyke is being designed to act initially as an alternative to CMake. I'm no expert in CMake, and many of the below may also apply to it, but I wanted to build pyke as a personal project, and use it in other projects of my own.\n\n- **Minimal artifacts**\nWithin a project, the only artifacts that result from a build operation are the intermediate files from the build itself (.o files, specifically, for C-family projects) and the final output. The only necessary support file in a project is the make.py file itself, probably at the project root folder.\n\n- **Flexibility**\nOf course, the pyke project file doesn't have to be at the root of a project. And it doesn't have to be called make.py. A pyke file can specify specific anchor directories for project files and generated artifacts. Command-line overrides can modify them in times of need.\n\n- **Just-beyond-declarative configuration**\nUsually, a declarative syntax is desireable for systems like this. But even CMake is a sort of language, and pyke files are too--just, in python. Very basic python is all you need to know to use it fully, and when you need that convenience of a full language, it's very nice to have. Sane defaults and a simple object structure help keep things fairly minimal for a basic project.\n\n- **Extensibility**\nPyke comes with some basic classes (called `Phase`s) which can manage basic tasks. But you may have special needs in your project tha require a specific tool to be run, or files to be moved around, or secret keys to be managed, etc. If it's not in the basic set of classes, build your own. It's a reasonable interface to design new functionality for.\n\n## Installing pyke\n\nCouldn't be easier. You need to be running python3.10 at least, and have pip installed. To install it globally:\n\n```\n$ python3 -m pip install pyke-build\n```\n\nor,\n\n```\n$ python3 -m pip install --user pyke-build\n```\n\nYou can optionally put it in a virtual environment, which may be the better idea.\n\nAlternatively, you can clone this repo and install locally:\n\n```\n$ git clone https://github.com/spacemeat/pyke\n$ cd pyke\n$ python3 -m pip install .\n```\n\n## Using pyke\n\nWe'll do a simple example. We have a C project laid out like this:\n\n```\nsimple_app\n\u251c\u2500\u2500 include\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 abc.h\n\u2514\u2500\u2500 src\n \u251c\u2500\u2500 a.c\n \u251c\u2500\u2500 b.c\n \u251c\u2500\u2500 c.c\n \u2514\u2500\u2500 main.c\n```\n\nWe want to build each .c file to an object, and link the objects together. Let's make a file called make.py, and place it in the root. \n\n```python\nfrom pyke import CompileAndLinkToExePhase, get_main_phase\n\nphase = CompileAndLinkToExePhase({\n 'name': 'simple',\n 'sources': ['a.c', 'b.c', 'c.c', 'main.c'],\n})\n\nget_main_phase().depend_on(phase)\n```\n\nNow it's as simple as invoking pyke:\n\n```\n$ pyke build\n```\n\nThe project was quietly built in a subdirectory:\n\n```\n\u251c\u2500\u2500 build\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 simple_app.gnu.debug\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bin\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 simple\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 int\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 a.o\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 b.o\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 c.o\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 main.o\n\u251c\u2500\u2500 include\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 abc.h\n\u251c\u2500\u2500 make.py\n\u2514\u2500\u2500 src\n \u251c\u2500\u2500 a.c\n \u251c\u2500\u2500 b.c\n \u251c\u2500\u2500 c.c\n \u2514\u2500\u2500 main.c\n```\n\nwhere `build/simple_app.gnu.debug/bin/simple` is the final binary executable.\n\nOf course, this is a very minimal example, and much more configuration is possible. \n\n## The `make.py` file\n\nSo what's in this `make.py` file? The general execution is to start pyke, and pyke will then find your `make.py` makefile in the current directory (your project root). Pyke will import the makefile, run it, and then begin executing actions based on what your makefile has configured and what you specify on the command line. All `make.py` does, in the simple cases, is add `Phase`-derived objecs to a provided top-level `ProjectPhase` object. Pyke does the rest.\n\nSo in the example above, first `make.py` imports the important pyke symbols. Then it sets up a single phase: `CompileAndLinkToExePhase`. In its definiton are two options: `name` and `sources`: the specific C source files. Then this phase is added as a `dependency` to a provided main `ProjectPhase`. That's all pyke needs to know how to build.\n\nPyke always begins with the phase object (a `ProjectPhase` instance), for the whole project. It can be accessed through `pyke.get_main_phase()`, which returns the phase. The CompileAndLinkToExePhase is then registered to the project via the `depend_on()` method. Pyke will use the phases it's given and the options set to each phase, along with the command line arguments, to perform the needed tasks: In this example, it will make the appropriate directories, invoke gcc or clang with configured arguments (in a POSIX environment), and optionally report its progress.\n\n### So how does pyke know where to find the sources? Or the headers? Or where to put things?\n\nEvery `Phase`-derived class defines its own default options, which give a default configuration for its actions. As an example, one option in `CompileAndLinkToExePhase` is `src_dir`, which specifies the directory relative to the project root (actually an achor directory, but mnore on that later) where source files can be located. The default is \"src\", which also happens to be where simple's source files are stored. Similarly, simple's headers are stored in \"include\", and `CompileAndLinkToExePhase` has another option named `include_dirs` which contains \"[include]\". Note that this is a `list` of length one, holding the default directories where include files are to be found. When it comes time to build with, say, `gcc`, the `include_dirs` value becomes \"-Iinclude\", and the source files are given as source arguments to `gcc`. There is more to the story of how directories are determined, but this suffices for the moment.\n\nEvery option can have its default value modified or replaced. If your source files are stored in a different directory (say, \"source\" instead of \"src\"), you can add `'src_dir': 'source'` to the phase definition, and pyke will find the files.\n\n> You can also set `src_dir` to \"'.'\", the dot directory, and explicitly path each source file, like:\n> `\"'sources': ['src/a.c', 'src/b.c', 'src/c.c', 'src/main.c']\"`\n> Though, of course, that's just more typing.\n\n### Interpolation, basically\n\nIn a nutshell, a string value in an option can have all or part of it enclosed in `{}`. This specifies an interpolation, which is simply to replace that portion of the string with the option given by the name in braces. The name is recursively looked up in the options table for that phase, its string values interpolated the same way, and returned to replace. We'll get into detail and examples below.\n\n> It should be noted that most of these options so far are actually contained in a `Phase`-derived class called `CFamilyBuildPhase`, which `CompileAndLinkToExePhase` derives from. This is because several other `CFamilyBuildPhase`-derived classes make use of the same options. It works just the same, since derived phase class inherit their supers' options.\n\n## Phases\n\nMost phases generally represent the transformation of files--inputs to outputs. Any useful build phase will have input files and output files. Some of these may be source, authored by developers. Some may be created by compiling source to objects, linking objects to executables or libraries, cloning repositories, or running code generation tools. When the outputs of one phase are the inputs of another, the one is a `dependency` of the other. Dependencies are set in the makefile explicitly, and their output->input mechanistry is automatic once set.\n\nEach operation of a build, such as the compilation of a single source file, may have a dedicated phase. C/C++ builds that are more complex than \"simple\" above may have a `CompilePhase` instance dedicated to each single source file->object file transformation, and one for each link operation, etc. Phases can be `cloned`, and their options as set at the time of cloning are copied with them. So, a template `CompilePhase` can be preset, and each clone made have its requisite source file set to `src`. Each `CompilePhase` object would then be set as a dependency of a `LinkToExePhase` object, which will automatically gather the generated object files from each `CompilePhase` for linking. Such an example makefile might look like this (with an additional few source files in a differnt directory, for spice):\n\n```python\n'multiphase cloned test'\n\nimport pyke as p\n\nc_to_o_phases = []\n\nproto = p.CompilePhase()\n\nfor src in ('a.c', 'b.c', 'c.c', 'main.c'):\n c_to_o_phases.append(proto.clone({'name': f'compile_{src}', 'sources': [src]}))\n\nproto = p.CompilePhase({\n 'src_dir': 'exp',\n 'obj_dir': 'int/exp',\n})\n\nfor src in ('a.c', 'b.c'):\n c_to_o_phases.append(proto.clone({'name': f'compile_exp_{src}', 'sources': [src]}))\n\no_to_exe_phase = p.LinkToExePhase({\n 'name': 'link',\n 'exe_basename': 'simple_1',\n}, c_to_o_phases)\n\np.get_main_phase().depend_on(o_to_exe_phase)\n```\n\nHere, we're creating a prototype `CompilePhase` object, and storing clones of it, one for each compile operation, in a list. Those phases become dependencies of the `LinkToExePhase` object, which in turn is set to the main project phase.\n\n### Built-in phases\n\nPyke comes with some built-in `Phase` classes--not many yet, but it's early still:\n* `class Phase`: Common base class for all other phases.\n* `class CommandPhase(Phase)`: A generic shell command phase. Often serves as a base class for a custom build step.\n* `class CFamilyBuildPhase(Phase)`: Common base class for building C and C++ projects. You won't decleare objecs of this type, but rather subclasses of it, as it does not actually implement many `action`s.\n* `class CompilePhase(CFamilyBuildPhase)`: Phase for compiling a single source file to a single object file.\n* `class ArchivePhase(CFamilyBuildPhase)`: Phase for building static libraries out of object files.\n* `class LinkToSharedObjectPhase(CFamilyBuildPhase)`: Phase for linking objects together to form a shared object (dynamic library).\n* `class LinkToExePhase(CFamilyBuildPhase)`: Phase for linking objects together to form an executable binary.\n* `class CompileAndArchive(CFamilyBuildPhase)`: Phase for combining compile and archive operations into one phase.\n* `class CompileAndLinkToSharedObjectPhase(CFamilyBuildPhase)`: Phase for combining compile and link operations into one phase for building a shared object.\n* `class CompileAndLinkToExePhase(CFamilyBuildPhase)`: Phase for combining compile and link operations into one phase for building an executable.\n* `class ProjectPhase(Phase)`: Project phase, which represents a full project. You can create multiple projects as dependencies of `get_main_phase()`, each their own subproject with compile and link phases, etc. The top-level phase of a makefile is always a project phase.\n\nAn easier view of the class heierarchy:\n```\nPhase\n\u251c\u2500\u2500 CommandPhase\n\u251c\u2500\u2500 CFamilyBuildPhase\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 CompilePhase\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 ArchivePhase\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 LinkToSharedObjectPhase\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 LinkToExePhase\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 CompileAndArchive\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 CompileAndLinkeToSharedObjectPhase\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 CompileAndLinkToExePhase\n\u251c\u2500\u2500 ProjectPhase\n```\n\n### Dependencies\n\nAs mentioned, dependencies among phases are set in the makefile. There are several things to know about dependency relationships:\n* Mostly what dependencies do is generate the files other dependent phases need.\n* They cannot be cyclical. The dependency graph must not contain loops, though diamond relationships are fine.\n* Option overrides and actions that are specified to multiple phases in a dependency tree happen in reverse depth-first order. The deepest dependency phases act first; this way, dependencies that build objects will happen before those that depend on them to build libraries, etc. When setting actions and overrides from the command line, the default is to set them to all phases, so whole dependency graphs can be levered at once.\n\nIf your project has multiple steps to build static libraries or shared objects (dynamic libraries) which are then used by other binaries in the build, you can make them dependencies of the built binary phases that use them. The appropriate directories and file references will automatically be resolved. Further, depnding on the properties of the project, appropriate dynamic lookup options will be inserted as well (like `-rpath` options for UNIX-like systems).\n\n## Actions\n\nPyke is not just good for building. There are other standard actions it can perform, with more forthcoming. Actually, it's more correct to say that `Phase` objects perform actions. Any string passed as an action on the command line will be applied to the appropriate phases which implement the action. If no phase supports the action, it is quietly ignored.\n\nThere is a default action (`report_actions`) which displays the available actions in each phase of a project. This default can be overridden in a config file, either in a project or under $HOME (see [configuring pyke](#configuring-pyke)), to make the default action something different.\n\n### Built-in actions\n\nCurrently, the supported actions in each built-in phase are:\n\n|phase class|actions\n|---|---\n|Phase|clean; clean_build_directory; report_actions; report_files; report_options\n|CommandPhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options) \n|CFamilyBuildPhase|(inherited: clean; clean_build_directory; report_actions; report_files; report_options)\n|CompilePhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)\n|ArchivePhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)\n|LinkToSharedObjectPhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)\n|LinkToExePhase|build; run; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)\n|CompileAndArchivePhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)\n|CompileAndLinkToSharedObjectPhase|build; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)\n|CompileAndLinkToExePhase|build; run; (inherited: clean; clean_build_directory; report_actions; report_files; report_options)\n|ProjectPhase|(inherited: clean; clean_build_directory) (all other actions are the responsiblity of dependencies)\n\nThese can be spcified on the command line. Multiple actions can be taken in succession; see below for CLI operation.\n\n* `report_options` prints a report of all phases and their options and overrides. This is useful to check that your command line overrides are doing what you think.\n* `report_files` prints a report of the files that are used and generated by each phase.\n* `report_actions` prints a report of all the actions each phase will respond to.\n* `clean` specifies that a phase will delete the files it is responsible for making.\n* `clean_build_directory` specifies that the entire build directory tree will be deleted.\n* `build` is the build action. This generates the build artifacts.\n* `run` runs built executables in place. Note that CommandPhase commands happen on the `build` action.\n\n### Action aliases\n\nThere are built-in aliases for the defined actions, to save some effort:\n\n|alias|actions\n|---|---\n|opts|report_options\n|files|report_files\n|actions|report_actions\n|c|clean\n|cbd|clean_build_directory\n|b|build\n\n### Action mapping\n\nYou may wish to associate one action to another. For example, an executable that `build` creates may itself be part of a later `build` action, but it can run only on the `run` action. You can wire up an action to be performed on another action by setting a particular `action map` as an option:\n\n```python\ndoc_builder = p.CompileAndLinkToExePhase({\n ...\n 'action_map': { 'build_docs': [ 'build', 'run' ]},\n ...\n})\n```\n\nThis specifies that, on the `build_docs` action, this phase should run its `do_action_build` method, followed by its `do_action_run` method. This allows for some flexibility in the action set for your makefile, especially if you're using a built-in or 3rd-party phase class.\n\n## Options\n\nOptions do not have to be strings. They can be any Python type, really, with the following criteria:\n\n* Options should be *convertible* to strings.\n* Options must be copyable (via `copy.deepcopy()`).\n\nWe've already seen list-type options, like `sources`, and there are several of those in the built-in phase classes. Custom ANSI colors for output are stored as dictionaries of dictionaries. And of course, any phase class you create can use any new option types you desire, as long as they meet the above criteria.\n\n### Overrides are stacked\n\nWhen an option is applied to a phase which already has as option by the same name, it is called an `override`. The new option displaces or modifies the existing one, but it does not replace it internally. Rather, it is pushed onto the option's *stack* of values, and can later be *popped* to undo the modification. In this way, an override can, say, remove an entry from an option's listed elements, and later popping of that override will bring it back.\n\n### Override operators\n\nSo how does one specify that an override *modifies* an option, instead of *replacing* it? When specifying the name of the option to set with `-o`, you can provide '+=' or '-=' or another operator to specify the modifier. A few option types get special behavior for this syntax:\n\n|original type|operator|override type|effect\n|---|---|---|---\n|any|=, none|any|the option is replaced by the override\n|bool|!= |bool|logical negation of the boolean value\n|int\\|float|+=, -=, *=, /=|int\\|float|performs standard math operations\n|string|+= |any|appends str(override) to the end of the string\n|string|-= |string|removes the first instance of the override string from the string\n|list|+= |any|the override is appended to the list\n|list|*= |list\\|tuple|the override elements extend the list\n|list|-= |any|the override is removed from the list\n|list|\\\\= |int|the override specifies an index to remove from the list\n|list|\\\\= |list[int]\\|tuple[int]\\|set[int]|the override specifies a collection of indices to remove from the list\n|tuple|+= |any|the override is appended to the tuple\n|tuple|*= |list\\|tuple|the override elements extend the tuple\n|tuple|-= |any|the override is removed from the tuple\n|tuple|\\\\= |int|the override specifies an index to remove from the tuple\n|tuple|\\\\= |list[int]\\|tuple[int]\\|set[int]|the override specifies a collection of indices to remove from the list\n|set|+=, \\|=|any non-set|the override is added to the set\n|set|-= |any|the override is removed from the set\n|set|\\|= |set|the result is unioned with the set \n|set|&= |set|the result is intersected with the set\n|set|\\\\= |set|the result is the difference with the set\n|set|^= |set|the result is the symmetric difference with the set\n|dict|+= |dict|the result is the union with the dict\n|dict|-= |any|the entry is removed from the dict by key\n|dict|\\|= |dict|the result is the union with the dict\n\nWe'll see some examples below.\n\n### Viewing options\n\nThe base `Phase` class defines the `report_options` action, with an alias of `opts`. This action prints the phases in depth-first dependency order, and each phase's full set of options in both raw, uninterpolated form, and fully interpolated form. This makes it easy to see what options are available, the type each is set to by default, and how interpolation and override operations are affecting the final result. It's handy for debugging a difficult build.\n\n```\n$ pyke opts\nname =\n = compile_and_link\n = simple\n -> simple\ngroup = \n = simple_app\n -> simple_app\nreport_verbosity: = 2\n -> 2\nreport_relative_paths: = True\n -> True\nverbosity: = 0\n -> 0\nnone: = None\n -> None\ntrue: = True\n -> True\nfalse: = False\n -> False\nproject_anchor: = /home/schrock/src/pyke/tests/simple_app\n -> /home/schrock/src/pyke/tests/simple_app\ngen_anchor: = /home/schrock/src/pyke/tests/simple_app\n -> /home/schrock/src/pyke/tests/simple_app\n...\n```\n\nEach option is listed with all its stacked raw values, followed by the interpolated value. Notice above that the default value of \"verbosity\" is set to 0. This makes build actions behave without output (unless there is an error). We can easily see how command-line overrides affect the results. More on how to set them below, but overriding the `verbosity` option with `2` looks like this:\n\n```\n$ pyke -o verbosity=2 opts\n...\nverbosity: = 0\n = 2\n -> 2\n...\n```\n\nHere, `verbosity` has been overridden, and has a second value on its stack. Subsequent actions will report more information based on the verbosity value.\n\nThe detailed report from `report_options` (`opts`) is what you get at `report_verbosity` level `2`. If you want to see only the interpolated values, you can override the `report_verbosity` option to `1`:\n\n```\n$ pyke -o report_verbosity=1\nname: -> simple\ngroup: -> \nreport_verbosity: -> 1\nreport_relative_paths: -> True\nverbosity: -> 0\nproject_anchor: -> /home/schrock/src/pyke/demos/simple_app\ngen_anchor: -> /home/schrock/src/pyke/demos/simple_app\n...\n```\n\nLike actions, there are argument aliases for some options. `-v2` sets the verbosity to 2, and `-rv1` sets the report_verbosity to 1. There are others as well.\n\n### Interpolation\n\nThe details on interpolation are straighforward. They mostly just work how you might expect. A portion of a string value surrounded by `{}` may contain a name, and that name is then used to get the option by that name. The option is converted to a string, if it isn't already (it probably is), and replaces the substring and braces inline, as previously explained. This means that interpolating an option which is a list will expand that list into the string:\n```\n$ pyke -o formatted_list_of_srcs=\"'Sources: {sources}'\" opts\n...\nformatted_list_of_sources: = Sources: {sources}\n -> Sources: ['a.c', 'b.c', 'c.c', 'main.c']\n...\n```\n\nIf the entire value of an option is interpolated, rather than a substring, then the value is replaced entirely by the referenced option, and retains the replacement's type. This is useful for selecting a data structure by name, as explained below.\n\n#### Nested interpolated strings\n\nOne useful feature is that interpolations can be nested. `CFamilyBuildPhase` uses this in places to help resolve selectable options. Look carefully at `kind_optimization`'s raw value below. It contains four `{}` sets, two inside the outer, and one nested even deeper. The inner set is interpolated first, and then the outer set according to the new value.\n\n```\n$ pyke report\n...\nkind: = debug\n -> debug\n...\ntool_args_gnu: = gnuclang\n -> gnuclang\ntool_args_clang: = gnuclang\n -> gnuclang\n...\ngnuclang_debug_optimization: = 0\n -> 0\n...\ngnuclang_release_optimization: = 2\n -> 2\n...\noptimization: = {{tool_args_{toolkit}}_{kind}_optimization}\n -> 2\n...\n```\n\nSo `optimization` evolves as:\n\n```\noptimization: -> {{tool_args_{toolkit}}_{kind}_optimization}\n -> {{tool_args_gnu}_{kind}_optimization}\n -> {gnuclang_{kind}_optimization}\n -> {gnuclang_debug_optimization}\n -> 0\n```\n\nNow, when overriding `kind`, a different version of the optimization flags (passed as `-On` to gcc, say) will be automatically interpolated:\n\n```\n$ pyke -o kind=release opts\n...\nkind: = debug\n = release\n -> release\n...\noptimization: = {{tool_args_{toolkit}}_{kind}_optimization}\n -> 2\n...\n```\n\n### Overriding in the makefile\n\nWhen constructing phase objects, the options you declare are technically overrides, if they happen to have the same name as any inherited options. They are treated by default as replacements, though you can provide operators.\n\nYou can also explicitly override after phase creation:\n\n```python\nfrom pyke import CompileAndLinkToExePhase, Op, get_main_phase\n\nphase = CompileAndLinkToExePhase('simple_experiemtal', {\n 'sources': ['a.cpp', 'b.cpp', 'c.cpp', 'main.cpp'],\n 'include_dirs': Op('+=', 'include/exp') # appending to include_dirs\n})\n\nphase.push_opts({\n 'sources': Op('*=', [f'exp/{src}' for src in [ # extending sources\n 'try_this.cpp', 'maybe.cpp', 'what_if.cpp']])\n})\n\nget_main_phase().depend_on(phase)\n```\n\nNote the use of the `Op` class, which signals that the override is an operational modifier, not merely a replacement. The operator is expressed as a string. Overriding with a value directly instead of with `Op` implies a replacement ('=').\n\n> Note the difference between *appending* one item to a list with `+=`, as in the phase constructor above, and *extending* multiple items to the list with `*=`, as in the push_opts() call.\n\nYou can pop the override with `Phase.pop_opts(key)`.\n\n> `Phase.push_opts` is defined on `Phase` as:\n> ```python def push_opts(self, overrides: dict, include_deps: bool = False, include_project_deps: bool = False) ```\n> The boolean parameters tell pyke how to propagate overrides through dependency phases. `include_deps` includes dependencies which are not `ProjectPhase`s, and `include_project_deps` includes only `ProjectPhase` phases specifically. Options set in `Phase` constructors call `push_opts` with both set to `False`.\n\n### Overriding on the command line\n\nAs seen previously, overrides can be specified on the command line as well with `-o [phases:][option[op value]`. This can look similar to overrides in code (though you may need to enquote it):\n\n```\n$ pyke -ocolors=none build\n$ pyke -o \"compile:sources *= [exp/try_this.c, exp/maybe.c, exp/what_if.c]\" opts\n```\n\nString values can be in quotes if they need to be disambiguated from punctuation or shell interpolation. The usual escapements work with '\\\\'. Overrides you specify with `[]` are treated as lists, `()` as tuples, `{}` as sets, and `{:}` as dicts. Since option keys must only contain letters, numbers, and underscores, you can differentiate a single-valued set from an interpolation by inserting a comma, or specifically enquoting the string:\n\n```\n$ pyke -o \"my_set_of_one={foo,}\" ...\n$ pyke -o \"my_set_of_one={'foo'}\" ...\n```\n\nPython's built-in literals True, False, and None are defined as options, and can be interpolated as {true}, {false}, and {none}.\n\nMuch like older-style subshell invocation, you can enquote a shell command in \\`backtick\\`s, and the command will be executed, with its output inserted in place. This is most useful in config files, since they're not executed in a shell context.\n\nThere is more to say about how value overrides are parsed. Smartly using quotes, commas, or spaces to differentiate strings from interpolators will usually get you where you want. Generally, though, setting options in the makefile will probably be preferred.\n\n### Base pyke options\n\nThere are a few options that are uiversal to pyke, regardless of the type of project it is running. Here are the options you can set to adjust its behavior:\n\n|option|default|usage\n|---|---|---\n|name |'' |The name of the phase. You should likely override this.\n|group |'' |The group name of the phase. Informed by its nearest dependent project phase.\n|report_verbosity |2 |The verbosity of reporting. 0 just reports the phase by name; 1 reports the phase's interpolated options; 2 reports the raw and interpolated options.\n|report_relative_paths |True |Whether to print full paths, or relative to $CWD when reporting.\n|verbosity |0 |The verbosity of non-reporting actions. 0 is silent, unless there are errors; 1 is an abbreviated report; 2 is a full report with all commands run.\n|none |None |Interpolated value for None.\n|true |True |Interpolated value for True.\n|false |False |Interpolated value for False.\n|project_anchor |project_root |This is an anchor directory for other directories to relate to when referencing required project inputs like source files.\n|gen_anchor |project_root |This is an anchor directory for other directories to relate to when referencing generated build artifacts like object files or executables.\n|build_dir |'build' |Top-level build directory.\n|colors_24bit |color_table_ansi_24bit |24-bit ANSI color table.\n|colors_8bit |color_table_ansi_8bit |8-bit ANSI color table.\n|colors_named |color_table_ansi_named |Named ANSI color table.\n|colors_none |color_table_none |Color table for no ANSI color codes.\n|colors_dict |'{colors_{colors}}' |Color table accessor based on {colors}.\n|colors |supported_terminal_colors |Color table selector. 24bit|8bit|named|none\n|action_map |{} |Routes action invocations to action calls.\n|toolkit |'gnu' |Select the system build tools. gnu|clang\n|kind |'debug' |Sets debug or release build. You can add your own; see the README.\n|version_major |'0' |Project version major value\n|version_minor |'0' |Project version minor value\n|version_patch |'0' |Project version patch value\n|version_build |'0' |Project version build value\n|version |'{version_mmp}' |Dotted-values version string.\n\nWhen running pyke from a directory that is different from your makefile's directory, you can specify the makefile path with `-m`. This is discussed below, but by default both the project root directory (`project_anchor`) and generated output root directory (`gen_anchor`) are relative to the makefile's directory, regardless of where you invoke from. However, this behavior can be modified. By overriding `gen_anchor` to a different directory in your file system, you can cause all the generated outputs to be placed anywhere. The generated directory structure remains the same, just at a different root location. Note that intermediate files which are inputs of later phases, like compiled object files, are still resolved correctly, as *any* generated file is rooted by `gen_anchor`. Likewise, any file that is expected as part of the project inputs created by developers (anything you might check in to your project repository, say) is anchored by `project_anchor`.\n\nIf you don't want your makefile to be situated at the project root, overriding `project_anchor` (possibly in the makefile itself) to the actual project root will line things up.\n\n### C/C++ specific options\n\nPyke began as a build tool for C and C++ style projects. The requisite classes are those that derive from `CFamilyBuildPhase`, and have lots of options for controlling the build. Note that since clang and gcc share much of the same command arguments, their toolchain-specific arguemts are often combined into a single definition.\n\n|option|default|usage\n|---|---|---\n|language |'c++' |Sets the source language. c|c++\n|language_version |'23' |Sets the source language version.\n|gnuclang_warnings |['all', 'extra', 'error'] |Sets the warning flags for gnu and clang tools.\n|gnuclang_debug_debug_level |'2' |Sets the debug level (-gn flga) for gnu and clang tools when in debug mode.\n|gnuclang_debug_optimization |'g' |Sets the optimization level (-On flag) for gnu and clang tools when in debug mode.\n|gnuclang_debug_flags |['-fno-inline', '-fno-lto', '-DDEBUG'] |Sets debug mode-specific flags for gnu and clang tools.\n|gnuclang_release_debug_level |'0' |Sets the debug level (-gn flga) for gnu and clang tools when in release mode.\n|gnuclang_release_optimization |'2' |Sets the optimization level (-On flag) for gnu and clang tools when in release mode.\n|gnuclang_release_flags |['-DNDEBUG'] |Sets release mode-specific flags for gnu and clang tools.\n|gnuclang_additional_flags |[] |Any additional compiler flags for gnu and clang tools.\n|definitions |[] |Macro definitions passed to the preprocessor.\n|posix_threads |False |Enables multithreaded builds for gnu and clang tools.\n|relocatable_code |False |Whether to make the code position-independent (-fPIC for gnu and clang tools).\n|rpath_deps |True |Whether to reference dependency shared objects with -rpath.\n|moveable_binaries |True |Whether to condition the build for dependencies which can be relatively placed. (-rpath=$ORIGIN)\n|include_dirs |['include'] |List of directories to search for project headers, relative to {include_anchor}.\n|sources |[] |List of source files relative to {src_anchor}.\n|lib_dirs |[] |List of directories to search for library archives or shared objects.\n|libs |{} |Collection of library archives or shared objects or pkg-configs to link. Format is: { 'foo', type } where type is 'archive' | 'shared_object' | 'package'\n|prebuilt_obj_dir |'prebuilt_obj' |Specifies the directory where prebuilt objects (say from a binary distribution) are found.\n|prebuilt_objs |[] |List of prebuilt objects to link against.\n|build_detail |'{group}.{toolkit}.{kind}' |Target-specific build directory.\n|obj_dir |'int' |Directory where intermediate artifacts like objects are placed.\n|obj_basename |'' |The base filename of a taret object file.\n|posix_obj_file |'{obj_basename}.o' |How object files are named on a POSIX system.\n|thin_archive |False |Whether to build a 'thin' archive. (See ar(1).)\n|archive_dir |'lib' |Where to emplace archive library artifacts.\n|archive_basename |'{name}' |The base filename of a target archive file.\n|posix_archive_file |'lib{archive_basename}.a' |How archives are named on a POSIX system.\n|rpath |{} |Collection of library search paths built into the target binary. Formatted like: { 'directory': True } Where the boolean value specifies whether to use $ORIGIN. See the -rpath option in the gnu and clang tools. Note that this is automatically managed for dependency library builds.\n|shared_object_dir |'lib' |Where to emplace shared object artifacts.\n|shared_object_basename |'{name}' |The base filename of a shared object file.\n|generate_versioned_sonames |False |Whether to place the version number into the artifact, and create the standard soft links.\n|so_major |'{version_major}' |Shared object major version number.\n|so_minor |'{version_minor}' |Shared object minor version number.\n|so_patch |'{version_patch}' |Shared object patch version number.\n|posix_so_linker_name |'lib{shared_object_basename}.so' |How shared objects are unversioned-naemd on POSIX systems.\n|posix_so_soname |'{posix_so_linker_name}.{so_major}' |How shared objects are major-version-only named on POSIX systems.\n|posix_so_real_name |'{posix_so_soname}.{so_minor}.{so_patch}' |How shared objects are full-version named on POSIX systems.\n|posix_shared_object_file |'{posix_so_linker_name}' |The actual target name for a shared object. May be redefined for some project types.\n|exe_dir |'bin' |Where to emplace executable artifacts.\n|exe_basename |'{name}' |The base filename of a target executable file.\n|posix_exe_file |'{exe_basename}' |How executable files are named on POSIX systems.\n|run_args |'' |Arguments to pass when running a built executable.\n\n### Making sense of the directory optinos\n\nEach of the include, source, object, archive, static_object and executable directories are built from components, some of which you can change to easily modify the path. Pyke is opinionated on its default directory structure, but you can set it how you like.\n\n#### Include files\n```\ninc_dir = .\ninclude_anchor = {project_anchor}/{inc_dir}/\\<include directory\\>\ninclude_dirs = [include]\n```\nYou are encouraged to change `inc_dir` to set a base directory for all include directories. Pyke will reference `include_anchor` and `include_dirs` directly when building command lines; `inc_dir` is just there to construct the path.\n\n#### Source files\n```\nsrc_dir = src\nsrc_anchor = {project_anchor}/{src_dir}\n```\nYou are encouraged to change `src_dir` to set a base directory for all the source files. Note that there is only a single source directory specified. Pyke does not search for named files; rather, you need to explicitly specify each source's directory or path.\n\n#### Build base directory structure\n```\nbuild_dir = build\nbuild_detail = {kind}.{toolkit}\nbuild_anchor = {gen_anchor}/{build_dir}\nbuild_detail_anchor = {build_anchor}/{build_detail}\n```\nYou are encouraged to change `build_dir` to set a different base for generated files, and `build_detail` to control different buld trees. Pyke will reference `build_detail_anchor` and `build_dir` directly.\n\n#### Intermediate (object) files\n```\nobj_dir = int\nobj_basename = \\<source_basename\\> (named after either a source file or the phase name, depending on `intermediate_build` and the phase type)\nobj_file = {obj_basename}.o (.obj on Windows)\nobj_anchor = {build_detail_anchor}/{obj_dir}\nobj_path = {obj_anchor}/{obj_file}\n```\nYou are encouranged to change `obj_dir` to set a base directory for intermediate files. Pyke will only reference `obj_path` directly, and will override `obj_basename` for each source file.\n\n#### Binary (executable) files\n```\nexe_dir = bin\nexe_basename = {name}\nexe_file = {exe_basename} (with .exe on Windows)\nexe_anchor = {build_detail_anchor}/{exe_dir}\nexe_path = {exe_anchor}/{exe_file}\n```\nYou are encouraged to change `exe_dir` to set a base directory for executable files, and `exe_basename` to set the name of the executable. Pyke will only reference `exe_path` directly.\n\nSimilar options are defined for static archives and shared objects. Of course, you can change any of these, or make your own constructed paths.\n\n### Recursive makefiles\n\nYou can run another makefile within a makefile:\n\n```python\n# shaper/libs/make.py:\nimport pyke as p\nshape_lib = p.CompileAndLinkToArchive()\ns = shape_lib.clone({'name': 'sphere', 'sources': ['shapes/sphere.cpp']})\nc = shape_lib.clone({'name': 'cube', 'sources': ['shapes/cube.cpp']})\ni = shape_lib.clone({'name': 'icosohedron', 'sources': ['shapes/icosohedron.cpp']})\np.get_main_phase().depend_on([s, c, i])\n```\n```python\n# shaper/exe/make.py:\nimport pyke as p\n\nbase = p.run_makefile('../libs') # tries to load '../libs/make.py'\nlibs = [base.find_dep(lib) for lib in ('sphere', 'cube', 'icosohedron')]\nexe = p.CompileAndLinkToExePhase({'sources': ['main.c']}, libs)\np.get_main_phase().depend_on(exe)\n```\n\nHere, the makefile `../libs/make.py` is run. Its ProjectPhase is returned as `base`, and the phases it loaded can be found in its dependency tree. The `project_anchor` and `gen_anchor` options are preserved for each makefile, though you can change them manually. Each makefile will also load its cohabiting `pyke-config.json` file as well, unless you suppress it with a parameter:\n\n```python\n...\nbase = p.run_makefile('../libs', False) # does not load libs/pyke-config.py, even if it exists.\n...\n```\n\n## The CLI\n\nThe general form of a pyke command is:\n\n```\npyke [-v | -h | [-c]? [-m makefile]? ]? [[-p [phase[,phase]*]]* | [-o [phase[,phase]*:]key[op_value]]* | [phase[,phase]*:][action]* ]*\n```\n\nNotably, -o and action arguments are processed in command-line order. You can set the phases to use with each, setting some option overrides, performing actions, setting different options, perform more actions, etc. If no phases are specified, the overrides and actions apply to all phases, in reverse depth-first dependency order.\n\nThe command line arguments are:\n* `-v`, `--version`: Prints the version information for pyke, and exits.\n* `-h`, `--help`: Prints a help document.\n* `-m`, `--makefile`: Specifies the module (pyke file), or its directory if the pyke file is called 'make.py', to be run. Must precede any arguments that are not -v, -h, or -c. If no -m argument is given, pyke will look for and run ./make.py.\n* `-n`, `--noconfig`: Specifies that the `pyke-config.json` file adjacent to the makefile should not be loaded.\n* `-c`, `--report-config`: Prints the full combined configuration from all loaded config files, and exits.\n* `-p`, `--phases`: Specifies a subset of phases on which to apply subsequent overrides or actions, if such arguments do not provide their own. Each `-p` encountered resets the subgroup. Option and action arguments that provide their own phases overrule `-p` for that argument, but do not reset it.\n* `-o`, `--override`: Specifies an option override to apply to some or all phases for subsequenet actions. If the option is given as a key-op-value, the override is pushed; if it is only a key (with no operator-value pair) the override is popped.\n* `action`: Arguments given without switches specify actions to be taken on the indicated phases. Any action on any phase which doesn't support it is quietly ignored.\n\n### Referencing phases\n\nPhases have names (`short name`s), as seen, but also have `full name`s, given as \"group.name\". For each phase, if the group name is not explicitly set, it is overridden *after the makefile is run* to be the short name of the closest dependency *project phase*. Project phases are thereafter given the short name `project`. This naming scheme allows for subprojects to be referenced by the group name on the CLI. We'll see some examples.\n\nThe main project group is named according to the name of the makefile, unless it is specifically called `make.py`, in which it is name of the directory in which it resides. So, if your project's root contins the makefile, and is named like this:\n```\n~/src/asset_converter/make.py\n```\nThe project will be called \"asset_converter.project\". If, however, it is named like:\n```\n~/src/asset_converter/images_make.py\n```\nThe project will be called \"images_make.project\".\n\nDependency phases of any project phase which are not themselves project phases are specified by the dotted name. Maybe your `asset_converter` project has dependencies like this:\n\n```\nasset_converter (ProjectPhase)\n\u251c\u2500\u2500 image_converter (ProjectPhase)\n\u2502 \u2514\u2500\u2500 link (LinkToExePhase)\n\u2502 \u251c\u2500\u2500 compile_jpg (CompilePhase)\n\u2502 \u251c\u2500\u2500 compile_png (CompilePhase)\n\u2502 \u2514\u2500\u2500 compile_tga (CompilePhase)\n\u2514\u2500\u2500 mesh_converter (ProjectPhase)\n \u2514\u2500\u2500 link (LinkToExePhase)\n \u251c\u2500\u2500 compile_blender (CompilePhase)\n \u251c\u2500\u2500 compile_3ds (CompilePhase)\n \u2514\u2500\u2500 compile_dxf (CompilePhase)\n```\n\nHere, each phase will be fully named by its owning project phase and its non-project phase names:\n* `asset_converter.project`\n* `image_converter.project`\n* `image_converter.link`\n* `image_converter.compile_jpg`\n* `image_converter.compile_png`\n* `image_converter.compile_tga`\n* `mesh_converter.project`\n* `mesh_converter.link`\n* `mesh_converter.compile_blender`\n* `mesh_converter.compile_3ds`\n* `mesh_converter.compile_dxf`\n\nWhen referencing phases on the command line, you can always reference by full name. For convenience, you can omit the group name of the main project, and it will be implied. An @ symbol references all the phases in either the group, short name, or both. So, for simple_app, you can reference just the compile phase like:\n\n```\npyke -o compile:verbosity=2\npyke -o .compile:verbosity=2\npyke -o simple_app.compile:verbosity=2\n```\n\nBy default, if the phase names are not specified at all, then all phases are affected. In actuality, it uses phase name \"@.@\", and is usually what you'd want. For complicated projects with multiple ProjectPhases, each can be separately referenced precisely.\n\n```\npyke -okind=release -oimage_converter.@:kind=debug build\n```\n\nThe above performs a release build for most of the project, but a debug build for only the image_converter subproject. If you want to just build image_converter:\n\n```\npyke image_converter.@:build\n```\n\nNote that the naming is *not* strictly hierarchical, but rather, specifically `group.name`. Phases must always be uniquely named within a project (and will be automatically disambiguated if they're not).\n\n## Configuring pyke\n\nPyke has an internal cnofig which provides some convenient aliases. On startup, once pyke has found the makefile but before it is loaded, pyke looks for additional configs in the following order:\n* ~/.config/pyke/pyke-config.json\n* <makefile's directory>/pyke-config.json\n\nAn example config might look like this:\n\n```json\n{\n \"include\": [\"../pyke-config.json\"],\n \"argument_aliases\": {\n \"-noc\": \"-ocolors=none\",\n \"-bdb\": \"dbadmin:build\",\n \"-rdb\": [\n \"-odbadmin:run_args=\\\"-logging=TRUE -username=$DBADMIN_UNAME -password=$DBADMIN_PASSWD\\\"\",\n \"dbadmin:run\"\n ]\n },\n \"action_aliases\": {\n \"pf\": \"package_flatpak\",\n \"vac\": \"verify_appchecker\"\n },\n \"default_action\": \"build\",\n \"default_arguments\": [\n \"-v2\"\n ],\n \"cache_makefile_module\": \"true\"\n}\n```\n\nEach can contain the following sections:\n\n### Include files\n\nThese are paths to other JSON files which contribute to the configuration. They are loaded before the rest of this file's contents, which can add to or override as described below. Useful if you have distinct configuration for work projects vs. personal projects, or lots of pyke projects which all use the same options. Paths that start with '/' are absolute; otherwise, they are relative to this file's path.\n\n### Argument aliases\n\nThese are convenient shorthands for complex overrides, override-action pairs, or whatever you like. Their values cannot contain other argument alias names, but *can* contain action aliases, and are otherwise exactly as you'd type them on the CLI (except you don't need to enquote things that the shell might interpret). Multiple values must be housed in a list. Each config file adds to the list of argument aliases.\n\n### Action aliases\n\nActions can be aliased. These are one-for-one word replacements, and the action values must not be other action aliases, though you *can* have more than one alias for any given action. Each config file adds to the list of action aliases.\n\n### Default action\n\nThe default action is taken when no action is specified on a CLI. By default, this is set to `report_actions`. The value must not be an alias. Each config file overrides a set default action.\n\n### Default arguments\n\nCcontains a list of strings, each of which is a separate command line argument. These can be full names or aliases. They are placed consecutively directly after the -m argument, but before any -o or action arguments, on every invocation of pyke. It is a convenient way to customize the way pyke always works on your project or machine. Each config file appends to the list of default arguments.\n\n### Cache makefile module\n\nAllows the makefile's __cache__ to be generated by python. This might speed up complex builds, but they'd hvae to be really complex.\n\n## Advanced Topics\n\n### Adding new phases\n\nOf course, a benefit of a programmatic build system is extension. Building your own Phase classes shold be straightforward. You likely won't have to often.\n\nSay you need a code generator. It must make .c files your project compiles and links with extant source. You can write a custom Phase-derived class to do just this. This gets you into the weeds of `Step` and `Result` classes, and action steps. More help will be provided in the future, but for now, let's just look at the code in demos/custom_phase/custom.py:\n\n```python\n''' Custom phase for pyke project.'''\n\nfrom functools import partial\nfrom pathlib import Path\nfrom pyke import (CFamilyBuildPhase, Action, ResultCode, Step, Result, FileData,\n input_path_is_newer, do_shell_command)\n\nclass ContrivedCodeGenPhase(CFamilyBuildPhase):\n '''\n Custom phase class for implementing some new, as-yet unconcieved actions.\n '''\n def __init__(self, options: dict | None = None, dependencies = None):\n super().__init__(options, dependencies)\n self.options |= {\n 'name': 'generate',\n 'gen_src_dir': '{build_anchor}/gen',\n 'gen_src_origin': '',\n 'gen_sources': {},\n }\n self.options |= (options or {})\n\n def get_generated_source(self):\n ''' Make the path and content of our generated source. '''\n return { Path(f\"{self.opt_str('gen_src_dir')}/{src_file}\"): src\n for src_file, src in self.opt_dict('gen_sources').items() }\n\n def compute_file_operations(self):\n ''' Implelent this in any phase that uses input files or generates output files.'''\n for src_path in self.get_generated_source().keys():\n self.record_file_operation(\n None,\n FileData(src_path.parent, 'dir', self),\n 'create directory')\n self.record_file_operation(\n FileData(Path(self.opt_str('gen_src_origin')), 'generator', self),\n FileData(src_path, 'source', self),\n 'generate')\n\n def do_step_generate_source(self, action: Action, depends_on: list[Step] | Step | None,\n source_code: str, origin_path: Path, src_path: Path) -> Step:\n ''' Performs a directory creation operation as an action step. '''\n def act(cmd: str, origin_path: Path, src_path: Path):\n step_result = ResultCode.SUCCEEDED\n step_notes = None\n if not src_path.exists() or input_path_is_newer(origin_path, src_path):\n res, _, err = do_shell_command(cmd)\n if res != 0:\n step_result = ResultCode.COMMAND_FAILED\n step_notes = err\n else:\n step_result = ResultCode.SUCCEEDED\n else:\n step_result = ResultCode.ALREADY_UP_TO_DATE\n\n return Result(step_result, step_notes)\n\n cmd = f'echo \"{source_code}\" > {src_path}'\n step = Step('generate source', depends_on, [origin_path],\n [src_path], partial(act, cmd=cmd, origin_path=origin_path, src_path=src_path),\n cmd)\n action.set_step(step)\n return step\n\n def do_action_build(self, action: Action):\n ''' Generate the source files for the build. '''\n def get_source_code(desired_src_path):\n for src_path, src in self.get_generated_source().items():\n if src_path == desired_src_path:\n return src.replace('\"', '\\\\\"')\n raise RuntimeError('Cannot find the source!')\n\n dirs = {}\n all_dirs = [fd.path for fd in self.files.get_output_files('dir')]\n for direc in list(dict.fromkeys(all_dirs)):\n dirs[direc] = self.do_step_create_directory(action, None, direc)\n\n origin_path = Path(self.opt_str('gen_src_origin') or __file__)\n\n for file_op in self.files.get_operations('generate'):\n for out in file_op.output_files:\n source_code = get_source_code(out.path)\n self.do_step_generate_source(action, dirs[out.path.parent],\n source_code, origin_path, out.path)\n```\n\nThere's a bit going on, but it's not terrible. Actions already implemented in `CFamilyBuildPhase` can clean generated source and the generation directory, as well as make directories for the build. The main work here is in generating the source files in an appropriate generation directory.\n\nIntegrating this custom phase into your makefile is as simple as making a new instance of the new phase, and setting it as a dependency of the build phase:\n\n```python\n'Bsic project with custom code generation phase'\n\n# pylint: disable=wrong-import-position\n\nfrom pathlib import Path\nimport sys\n\nsys.path.append(str(Path(__file__).parent))\n\nfrom custom import ContrivedCodeGenPhase\nimport pyke as p\n\ngen_src = {\n'd.c': r'''\n#include \"abc.h\"\n\nint d()\n{\n return 1000;\n}''',\n\n'e.c': r'''\n#include \"abc.h\"\n\nint e()\n{\n\treturn 10000; \n}'''\n}\n\ngen_phase = ContrivedCodeGenPhase({\n 'gen_src_origin': __file__,\n 'gen_sources': gen_src,\n})\n\nbuild_phase = p.CompileAndLinkToExePhase({\n 'name': 'simple',\n 'sources': ['a.c', 'b.c', 'c.c', 'main.c'],\n}, gen_phase)\n\np.get_main_phase().depend_on(build_phase)\n```\n\nAnd that's it. Now the `build` action will first generate the files in the right place if needed, and then build them if needed. The `clean` action will delete the generated files, and the `clean_build_directory` action will not only remove the build, but also the generated source directory.\n\n> A few notes: The above will only generate the source files if they don't exist, or are older than the makefile (which has the source text in it). Also, the gen diretory is based on `gen_anchor` (by way of `build_anchor`), which is necessary for any generated files to be built in the right place if you change `gen_anchor`'s value.\n\n#### Adding new actions\n\nTo add a new action to a custom phase, simply add a method to the phase class. For example, to add an action called \"deploy\", write a phase method like so:\n\n```python\n ...\n def do_action_deploy(self, action: Action) -> ResultCode:\n ...\n```\n(You'll want to import Action and ResultCode from pyke if you want the annotations.) That's all you need to do for the method to be called on an action, since actions' names are just strings, and pyke reflects on method names to find a phase that can handle the action. Of course, implmenting actions is more involved, as you can see above.\n\n### Adding new build kinds\n\nAdding new build kinds is straightforward if you're just trying to customize the system build commands. There are currently three that depend on the build kind: `debug_level`; `optimization`; and `flags`. For POSIX tools, these correspond to the `-g{debug_level}`, `-O{optimization}`, and `{flags}` of any definition. If you wanted a custom kind called \"smallest\", simply provide the following overrides, with perhaps these values:\n\n```\n'gnuclang_smallest_debug_level': '0',\n'gnuclang_smallest_optimization': 's',\n'gnuclang_smallest_flags': ['-DNDEBUG'],\n```\n\nWhen selecting the build kind with `-o kind=smallest`, these overrides will be selected for the build.\n\n### Setting colors\n\nThe colorful output can be helpful, but not if you're on an incapable terminal, or just don't like them or want them at all. You can select a color palette:\n\n```\npyke -o colors=none build\npyke -o colors=named build\npyke -o colors=8bit build\npyke -o colors=24bit build\n```\n\nDefining your own color palette is possible as well. You'll want to define all the named colors:\n\n```\npyke -o colors_custom=\"{ off: {form:off}, success: {form:b24, fg:[0,255,0], bg:[0,0,0]}, ...}\" -o colors=custom build\n```\n\nThat gets cumbersome. You can change an individual color much more easily:\n\n```\npyke -o \"colors_24bit|={shell_cmd: {form:b24, fg:[255, 255, 255]}}\"\n```\n\nThese are likely best set as default arguments in `$HOME/.config/pyke/pyke-config.json`. (See [configuring pyke](#configuring-pyke).):\n\n```json\n{\n \"default_arguments\": [\n \"-o colors_super = { off: { form: off }}\",\n \"-o colors_super |= { success: { form: b24, fg: (0x33, 0xaf, 0x55) }}\",\n \"-o colors_super |= { fail: { form: b24, fg: (0xff, 0x33, 0x33) }}\",\n \"-o colors_super |= { phase_lt: { form: b24, fg: (0x33, 0x33, 0xff) }}\",\n \"-o colors_super |= { phase_dk: { form: b24, fg: (0x23, 0x23, 0x7f) }}\",\n \"-o colors_super |= { step_lt: { form: b24, fg: (0xb3, 0x8f, 0x4f) }}\",\n \"-o colors_super |= { step_dk: { form: b24, fg: (0x93, 0x5f, 0x2f) }}\",\n \"-o colors_super |= { shell_cmd: { form: b24, fg: (0x31, 0x31, 0x32) }}\",\n \"-o colors_super |= { key: { form: b24, fg: (0x9f, 0x9f, 0x9f) }}\",\n \"-o colors_super |= { val_uninterp_lt: { form: b24, fg: (0xaf, 0x23, 0xaf) }}\",\n \"-o colors_super |= { val_uninterp_dk: { form: b24, fg: (0x5f, 0x13, 0x5f) }}\",\n \"-o colors_super |= { val_interp: { form: b24, fg: (0x33, 0x33, 0xff) }}\",\n \"-o colors_super |= { token_type: { form: b24, fg: (0x33, 0xff, 0xff) }}\",\n \"-o colors_super |= { token_value: { form: b24, fg: (0xff, 0x33, 0xff) }}\",\n \"-o colors_super |= { token_depth: { form: b24, fg: (0x33, 0xff, 0x33) }}\",\n \"-o colors_super |= { path_lt: { form: b24, fg: (0x33, 0xaf, 0xaf) }}\",\n \"-o colors_super |= { path_dk: { form: b24, fg: (0x13, 0x5f, 0x8f) }}\",\n \"-o colors_super |= { file_type_lt: { form: b24, fg: (0x63, 0x8f, 0xcf) }}\",\n \"-o colors_super |= { file_type_dk: { form: b24, fg: (0x43, 0x5f, 0x9f) }}\",\n \"-o colors_super |= { action_lt: { form: b24, fg: (0xf3, 0x7f, 0x0f) }}\",\n \"-o colors_super |= { action_dk: { form: b24, fg: (0xa3, 0x4f, 0x00) }}\",\n \"-o colors=super\"\n ]\n}\n```\n\nThe above colors are the default for 24-bit RGB colors. Change them however you like.\n\nAn individual color has the format:\n\n```\n{form: <format>, fg: <foreground-color>, bg: <background-color>}\n```\n\nFor b24 formats, each of fg and bg should specify a tuple of red, green, blue, from 0 through 255. For b8 formats, each of fg and bg should specify a single integer [0, 255] which matches the ANSI 8-bit color palette. For the named formats, the ANSI named colors are used, like 'red' and 'bright blue'. If you want to specify no color, leave the color dict empty. The 'off' color dict is special, and must be kept as '{form: off}'.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A python-based build system for automating build and deployment tasks.",
"version": "0.2.0",
"project_urls": {
"Repository": "https://github.com/spacemeat/pyke.git"
},
"split_keywords": [
"c",
" c++",
" build"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8ccd7992cf6742859153293bde955ad7a8d75f4f01f4893d95bc59058a1e81c1",
"md5": "25caf69d43316233ee472e8cb2af6642",
"sha256": "6677e65eab35dc38365b1f1f6c69b2f6c796d48d3e880956006e6b3831f9a09d"
},
"downloads": -1,
"filename": "pyke_build-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "25caf69d43316233ee472e8cb2af6642",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 61410,
"upload_time": "2024-05-11T01:21:07",
"upload_time_iso_8601": "2024-05-11T01:21:07.083863Z",
"url": "https://files.pythonhosted.org/packages/8c/cd/7992cf6742859153293bde955ad7a8d75f4f01f4893d95bc59058a1e81c1/pyke_build-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f99623f541d6af32f9ce77e2835f7965117320f6e0f19fac81a11a6022798330",
"md5": "ee27a6a68abe46ff0b9ec8143091b875",
"sha256": "2a2891412d0980bfe20dda59d9b9db5bba9866c8b9906a94e661f724ca208df3"
},
"downloads": -1,
"filename": "pyke_build-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "ee27a6a68abe46ff0b9ec8143091b875",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 100559,
"upload_time": "2024-05-11T01:21:10",
"upload_time_iso_8601": "2024-05-11T01:21:10.106217Z",
"url": "https://files.pythonhosted.org/packages/f9/96/23f541d6af32f9ce77e2835f7965117320f6e0f19fac81a11a6022798330/pyke_build-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-11 01:21:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "spacemeat",
"github_project": "pyke",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyke-build"
}
