Usually projects have different parts that need to be built independently or in different phases and that might, or might not, have interdependencies.
For example, imagnie a traditional native application. In such application there might be one or more libraries that need to be compiled in order to build the application, there will certainly be some unit tests for the libraries, and maybe some integration tests, there can also exist a documentation that also needs to be built, and then everything together can be combined to create an installer that will be our end deliverable.
Let’s take the following example:
# ------------------------------------------------- # build the library and the app # ------------------------------------------------- mylib = lib ('mylib', cc ('src/*.cc')) myapp = app ('myapp') # ------------------------------------------------- # build the tests # ------------------------------------------------- mylibtests = app ('mylibtets', cc ('tests/*.cc')) # ------------------------------------------------- # run tests # ------------------------------------------------- shell (mylibtests) # ------------------------------------------------- # generate documentation # ------------------------------------------------- outfolder = doxygen ('doxygen.config') # ------------------------------------------------- # generate deliverables # ------------------------------------------------- compress('myapp-v1.00.zip', [myapp, outfolder])
It is not hard to imagine such a project and an environment where everything is built automatically once every hour or once every change is submitted on the VCS.
But this is not how people works. You don’t want to build everything and pass all the tests every time you make a simple change on a file. You might want to build only a portion of the code to make sure it compiles, but not passing the tests or generating the installer, or maybe you want to do all things sometimes, ... but the thing is that it should be your choice.
To do this, there is a really simple way of structuring things inside a pyke project which is dividing all things that need to be built in groups or sections (see pyke.section()).
So you can have one section to build the libraries, the application and the tests, another to the tests, another to build the documentation and another one to create your deliverables or artifacts.
Check the example updated:
# ------------------------------------------------- # build the libs, the app and the tests by default # ------------------------------------------------- mylib = lib ('mylib', cc ('src/*.cc')) myapp = app ('myapp') mylibtests = app ('mylibtets', cc ('tests/*.cc')) # ------------------------------------------------- # run tests # ------------------------------------------------- section ('tests') shell (mylibtests) # ------------------------------------------------- # generate documentation # ------------------------------------------------- section ('docs') outfolder = doxygen ('doxygen.config') # ------------------------------------------------- # generate deliverables # ------------------------------------------------- section ('artifacts') compress('myapp-v1.00.zip', [myapp, outfolder])
Now, with the above example, you can run things like:
$ pyke
To build your library, app and tests.
In order to run your tests, you will only have to run:
$ pyke -t tests
Now, here there is an interesting feature, since the executable to run your tests depends on the test application to exist, and the test application depends on your library, if you make a change on a file in the library and run the command above, the library will be rebuilt, the test app will be generated again, and then, the tests will be executed, so everything is consistent :)
All dependencies are transparently managed by pyke. Anyway, if you want to execute the jobs on one section ignoring the dependencies with jobs on other sections, you can also run:
$ pyke --only tests
Finally, building everything on the example above would be as simple as running:
$ pyke -t artifacts
Specifies a new target section that will be executed only when running pyke with ‘-t’ parameter.
By default all jobs are created in the section ‘all’. Jobs under a new section are executed only when you run pyke with ‘-t’ parameter.
For example, if you add rules after section (‘test’), then, the only way of running those rules would be running:
$ pyke -t test
There are two special sections, ‘all’ which is the default for all pyke files that are processed, and the ‘clean’, which is for cleaning up a build, and are automatically created by all the builtin rules.
Example of usage:
# by default all scripts start as if you run next line (but you don't need to)
section ('all')
# run some rules here...
section ('test')
# run some other rules here...