🧑🍳 Cook
==========
.. image:: https://github.com/tillahoffmann/cook-build/actions/workflows/main.yaml/badge.svg
:target: https://github.com/tillahoffmann/cook-build/actions/workflows/main.yaml
.. image:: https://img.shields.io/pypi/v/cook-build
:target: https://pypi.org/project/cook-build
Cook is a task-centric build system with simple declarative recipes specified in Python.
Getting Started
---------------
Tasks are declared in a :code:`recipe.py` file using the :code:`~cook.manager.create_task` function. Each task must have a unique name, may depend on files or other tasks, and can execute an action, typically a shell command. The simple example below creates a C source file, compiles it, and executes the binary.
.. code-block::
>>> from cook import create_task
>>> create_task("src", targets=["hello.c"],
... action="echo 'int main() { return 0; }' > hello.c") # doctest: +IGNORE_RESULT
>>> create_task("cc", dependencies=["hello.c"], targets=["hello"],
... action="cc -o hello hello.c") # doctest: +IGNORE_RESULT
>>> create_task("hello", dependencies=["hello"], action="./hello") # doctest: +IGNORE_RESULT
Running :code:`cook ls` from the command line lists all known tasks, e.g.,
.. code-block::
:cwd: examples/getting_started
$ cook ls
<task `src` @ /.../recipe.py:3>
<task `cc` @ /.../recipe.py:4>
<task `hello` @ /.../recipe.py:5>
Running :code:`cook exec hello` creates the source file, compile it, and executes the binary. We use :code:`--log-level=debug` to provide additional information here.
.. code-block::
:cwd: examples/getting_started
:stderr:
$ cook --log-level=debug exec hello
DEBUG: <task `src` @ .../recipe.py:3> is stale because one of its targets is missing
DEBUG: started <task `src` @ .../recipe.py:3>
DEBUG: completed <task `src` @ .../recipe.py:3> in ... seconds
DEBUG: <task `src` @ .../recipe.py:3> created `hello.c`
DEBUG: <task `cc` @ .../recipe.py:4> is stale because one of its targets is missing
DEBUG: started <task `cc` @ .../recipe.py:4>
DEBUG: completed <task `cc` @ .../recipe.py:4> in ... seconds
DEBUG: <task `cc` @ .../recipe.py:4> created `hello`
DEBUG: <task `hello` @ .../recipe.py:5> is "stale" because it has no targets
DEBUG: started <task `hello` @ .../recipe.py:5>
DEBUG: completed <task `hello` @ .../recipe.py:5> in ... seconds
To rerun a task, tell Cook to reset it.
.. code-block::
:cwd: examples/getting_started
:stderr:
$ cook reset cc
INFO: reset 1 task
The full set of available commands can be explored using :code:`cook --help` as shown below.
.. cook --help
Tasks Are Dumb; Contexts Are Smart
----------------------------------
:code:`~cook.task.Task`\ s do not provide any functionality beyond storing metadata, including
- :code:`targets`, the files generated by the task,
- :code:`dependencies`, the files the task depends on,
- :code:`action`, the :code:`~cook.actions.Action` to execute when the task is run,
- :code:`task_dependencies`, other tasks that should be executed first,
- :code:`location`, filename and line number where the task was defined.
All logic is handled by :code:`~cook.contexts.Context`\ s which are applied to each task when it is created. For example, :code:`~cook.contexts.create_group` adds all tasks created within the context to a group. This group can be executed to execute all child tasks.
..
:hidden:
:maxdepth: 1
docs/interface