powermake 3.0.0a3

Yet another makefile tool. This one is meant to be super fast, super easy and crossplatform while leaving full power to the user at any time.

PowerMake

• PowerMake
  • TLDR
  • What is PowerMake?
  • Does PowerMake generate a Makefile like CMake ?
  • For which project is PowerMake suitable?
  • Advantages of PowerMake
  • Disadvantages of PowerMake
  • Philosophy
  • Installation
    • Install from Pypi: (RECOMMENDED)
    • install from sources: (NOT RECOMMENDED)
  • Quick Example
  • More examples
  • Tutorials
  • Documentation

TLDR

Use PowerMake to write cross-platform makefiles.
The idea is to create a python script and use python powermake library to compile all your project reliably with the least amount of effort as possible.

Create a python script using one of the models in examples.md

Then run:

python YOUR_SCRIPT.py -rv

And voilà, your program is compiled in release mode !

You want the debug mode ?
Just run:

python YOUR_SCRIPT.py -rvd

[!NOTE]
Here -r and -v options are completely optional,
type python YOUR_SCRIPT.py --help to have the description of all available options.

You want to clean/rebuild/test your program with a single command ?
What about this:

python YOUR_SCRIPT.py -crvt arg1 arg2 arg3

You can follow the tutorials or explore the documentation to learn about the infinite possibilities of PowerMake !! And if you are too lazy or completely lost, just ask what you are searching for in the Discussions section.

If you don't exactly understand why PowerMake is different from Make, CMake, XMake, Scons, etc..., you should read the Philosophy section.

What is PowerMake?

Powermake is a utility that compiles C/C++/AS/ASM code, just like Make, Ninja, CMake, or Xmake.

Its goal is to give full power to the user, while being cross-platform and easier to use than any other build system.

Powermake extends what is possible to do during the compilation by providing a lot of functions to manipulate your files and a lot of freedom on the way you will implement your makefile.
Powermake is entirely configurable, but for every behavior you haven't explicitly defined, PowerMake will do most of the job for you by detecting installed toolchains, translating compiler flags, etc...

Does PowerMake generate a Makefile like CMake ?

Not by default. PowerMake does not build on top of make, it replaces make.

Since PowerMake 1.20.0, Powermake is able to generate a Makefile, but this will never be as powerful as PowerMake, this feature is only used if you really need a GNU Makefile for compatibility with old deployments/tests scripts.

For which project is PowerMake suitable?

PowerMake was specifically designed for complex projects that have very complicated compilation steps, with a lot of pre-built tasks that need to be compiled on multiple operating systems with different options.

However, today, even for a 5 files project on Linux with GCC, PowerMake is more convenient than make because out of the box it provides a debug/release mode with different options and different build directories, it generates vscode debug files, it detects better than make when files need to be recompiled, it provides default rebuild/clean/install options without any configuration, etc...

Advantages of PowerMake

PowerMake is made to make the developer experience easier, faster and more enjoyable.
PowerMake is a breeze for the developers that hate the opacity and lack of quality of life features of CMake. Here are some of the reasons why:

• Very easy to read makefiles

  • Your makefile will just be a small python script that can be read from top to bottom, even by someone who has never used PowerMake.
  • No more huge GNU Makefiles, makefile.am or CMakeLists.txt that are impossible to read.

• Cross-Platform:

  • PowerMake can detect the compiler installed on your machine and give you an abstraction of the compiler syntax.
    • This currently works well with GCC/G++/Clang/Clang++/Clang-CL/MSVC/NASM/MASM, but other compilers will be added.
  • It is constantly tested in CI on Linux, macOS and Windows, on multiple architectures and cross-compiling against multiple architectures. It should also work on BSD systems or other Unix-like.

• No magic behaviors

  • Gives you complete control of what you are doing. Nothing is hidden and any behavior can be overwritten.
    • Missing features can always be written in the makefile.

• Smart automatic configurations

  • PowerMake has local and global config files, but on top of that, PowerMake is able to automatically find a value that makes sense for each field that is not explicitly assigned, you can easily have very basic configuration files (often no config file at all) and it will still work for most systems. For example just specifying that your linker path is i686-w64-mingw32-ld will be enough for PowerMake to detect that you are compiling in cross-compilation, for Windows 32 bits with a low level linker and the whole toolchain will be correctly set, the build folder will be correctly set and even the config.target_is_windows() method will return True.

• Stupidly easy Cross-compilation

  • CC=i686-w64-mingw32-gcc python makefile.py -rv is all you need to compile for Windows 32 bits from Linux (this is a consequence of the smart configurations listed above).
  • You can also use python makefile.py -rv --os Windows --arch x86 to do the same.

• Extremely fast:

  • Fast parallel compilation
  • No configure + build phase, just a single pass
  • Adding a file doesn't require to recompile the whole project

• Python power

  • Real loops, real functions, real string manipulation, real data structures, not a limited macro language bolted onto a config file format.

• IDE integration

  • PowerMake can generate vscode launch.json, tasks.json, settings.json and compile_commands.json for a perfect syntax highlighting and an easy graphical debugging session.

• Automatic flags translation

  • You write -Wall for example and on MSVC it's translated to /W3
  • You can use flags like -fanalyzer (only GCC) or -Weverything (only clang) and they will be automatically removed when not supported.

• Powerful package manager

  • PowerMake can automatically find libraries compatible with your linker in the version range you want, even when cross-compiling.
  • It's even able to download and compile any library from its sources.

Disadvantages of PowerMake

• Young project (began in 2024)

  • Retrocompatibility is supposed to be kept between versions, and we make a lot of tests in CI to reduce regressions, but they are still more likely than in a battle-tested solution like CMake.

• Small ecosystem

  • Don't expect CMake's ecosystem maturity, IDE support breadth, or huge community/Stack Overflow coverage. However, I (mactul) am always available to help you use the tool or implement your ideas.

• You have full control, the tool doesn't know what you are doing during the compilation steps

  • An example of this problem is that PowerMake can't know how many steps will be done during the compilation, so if you want PowerMake to print the percent of compilation elapsed, you have to manually specify the number of steps PowerMake will do.

Philosophy

All other Make-like utilities that I know parse a file to understand directives from it.

PowerMake does the opposite. You write a python script, you do whatever you like in this script and you call PowerMake functions to help you compile your code.
This gives you complete control; you can retrieve files from the web, read and write files, and even train a Neural Network if you want, and at any time you can use Powermake functions to help you in your compilation journey.

This also means that the philosophy is completely different from a tool like make.
When you read a GNU Makefile, you start at the end, the final target and you read each target dependency recursively before executing the task.
In a GNU Makefile, the order of each target doesn't reflect at all the order of execution.

Powermake is read as a script. The order of each instruction matters a great deal. The first step is read, if it needs to be executed, it's executed, then the next step is read, etc...

• The main advantage of this approach is that it's extremely easy to write and read the makefile, it's just a good old script that executes from top to bottom. You can also do loops, functions, etc... everything python offers, which is way more powerful than the make approach.
• The main disadvantage of this approach is that steps during the makefile can't automatically be parallelized. powermake.compile_files offers a good parallelization that counteracts this problem, but you have to compile most of your files in this function for this parallelization to have an effect. The worst thing you can do is loop over each one of your files and call this function for one file at a time.

Installation

[!WARNING]
In this documentation, the command python refers to python >= python 3.7.
On old systems, python and pip can refer to python 2.7, in this case, use python3 and pip3.

Install from Pypi: (RECOMMENDED)

pip install -U powermake

Don't hesitate to run this command regularly to benefit from new features and bug fixes.

install from sources: (NOT RECOMMENDED)

The main branch might be untested and might not work at all.
If you really want to install from sources, we suggest you to checkout to the latest tag and build from this point in the history.

pip install -U build twine
git clone https://github.com/mactul/powermake
cd powermake
# Checkout to the latest tag
git checkout $(git tag | tail -n1)
rm -rf ./dist/
python -m build
pip install -U dist/powermake-*-py3-none-any.whl --force-reinstall

Quick Example

This example compiles all .c and .cpp files that are recursively in the same folder as the python script and generate an executable named program_test

[!WARNING]
PowerMake calculates all paths from its location, not the location where it is run.
For example, python ./folder/makefile.py will do the same as cd ./folder && python ./makefile.py

[!NOTE]
In this documentation, we often assume that your makefile is named makefile.py, it makes things easier to explain. Of course, you can name your makefile the name you like the most.

import powermake


def on_build(config: powermake.Config):

    files = powermake.get_files("**/*.c", "**/*.cpp")

    objects = powermake.compile_files(config, files)

    print(powermake.link_files(config, objects))


powermake.run("program_test", build_callback=on_build)

[!TIP]
You can generate a new makefile for a project by using python -m powermake in the project's folder.
If pip's scripts folder (often ~/.local/bin) is in your path, you can also simply run powermake
For more details about this, see Generating a Powermake.

More examples

---

:pencil: See more examples here.

Tutorials

---

:bulb: Follow step-by-step tutorials here.

Documentation

---

:books: Read the documentation here.