pymaketool 3.0.0rc5

No project description provided

pymaketool

pymaketool is an elegant and simple tool to build and manage large C/C++ projects and libraries. The main purpose is to simplify the build process by using Python to find and organize source files.

📂 my_project/

• 📄 Makefile _{← root entry point}
• 📄 .env _{← environment variables (not committed)}
• 📂 pymake/ _{← build config folder}

  • 📄 Makefile.py _{✏️ YOU write this · toolchain · flags · targets}
  • 📄 makefile.mk _{← generated}
  • 📄 vars.mk _{← generated}
  • 📄 srcs.mk _{← generated}
  • 📄 targets.mk _{← generated}
• 📂 app/ _{← source module}

  • 📂 inc/

    • 📄 main.h
  • 📂 src/

    • 📄 main.c
  • 🐍 mk.py _{✏️ YOU write this · recommended}

    from pm import mk
    
    mk(srcs=["src/main.c"], incs=["inc"])
    

    ## Or just:
    from pm import mk
    
    mk()
    

    ## Or nothing at all:
    

• 📂 utils/ _{← another source module}

  • 📄 utils.c
  • 📄 utils.h
  • 🐍 utils_mk.py _{✏️ also supported}
• 📂 build/ _{← generated output}

  • ⚙️ app _{← final binary}
  • 📂 obj/

    • 📄 app/src/main.o
    • 📄 utils/utils.o

Quick Start

Install required packages:

Ubuntu

$ sudo apt-get install -y gcc make python3 python3-pip git time zip

Fedora

$ sudo dnf install python3 python3-pip time zip git gcc

Arch Linux

$ sudo pacman -S gcc make python python-pip time zip git

Install pymaketool:

$ pip3 install pymaketool

Create and build a new C project:

$ pynewproject CLinuxGCC
  (author) Your name: Ericson
  (project_name) Your project name: hello

$ cd hello
hello$ make
hello$ ./build/hello

Quick Start with Poetry

If you prefer Poetry for dependency management:

$ curl -sSL https://install.python-poetry.org | python3 -

$ pynewproject CLinuxGCC
  (project_name) Your project name: hello

$ cd hello
hello$ poetry init --name hello --dependency pymaketool
hello$ poetry install
hello$ poetry run make
hello$ ./build/hello

Quick start in Docker

$ docker pull ericsonjoseph/pymaketool
$ docker run -it ericsonjoseph/pymaketool
ubuntu@$ pynewproject CLinuxGCC

---

Module Files (mk.py, *_mk.py, *.mk.py)

pymaketool discovers module files recursively. The shortest and recommended name is mk.py, but app_mk.py and app.mk.py still work.

Each module file describes one folder of C/C++ code.

Recommended DX: from pm import mk

# app/mk.py
from pm import mk

mk()

That is enough for most modules. mk() captures the current file path and auto-discovers sources and includes in the same directory. If you want zero lines, an empty mk.py also works.

Common cases

Explicit files:

from pm import mk

mk(srcs=["src/main.c", "src/util.c"], incs=["inc"])

Exclude files from auto-discovery:

from pm import mk, skip

mk(srcs=skip("test*", "mock_*"), incs=[".", "include"])

C++ module:

from pm import mk

mk(lang="cpp")

When to use the class API

Use the class-based API only when you need custom module behavior, static libraries, or full control over discovery.

from pymakelib import module

@module.ModuleClass
class App(module.BasicCModule):
    pass

---

Project Configuration (Makefile.py)

Makefile.py is the project entry point. It defines the toolchain, compiler flags, and build targets.

New API — ProjectConfig (recommended)

# pymake/Makefile.py
from pymakelib import ProjectConfig, Makeclass, CompilerOpts, MKVARS, Target
from pymakelib.toolchain import get_gcc_linux

@Makeclass
class Build(ProjectConfig):
    name         = 'myapp'
    output_dir   = 'build/obj/'
    compiler_set = get_gcc_linux()   # or get_gcc_arm_none_eabi('/opt/arm/bin/')

    def compiler_opts(self, opts: CompilerOpts) -> CompilerOpts:
        opts.optimize     = ['-O2']
        opts.debugging    = ['-g3']
        opts.warnings     = ['-Wall']
        opts.standard     = ['-std=c11']
        opts.preprocessor = ['-MP', '-MMD']
        opts.macros       = {'VERSION': '"1.0"'}
        return opts

    def targets(self):
        return {
            'TARGET': Target(
                file   = f'build/{self.name}',
                script = [MKVARS.LD, '-o', '$@', MKVARS.OBJECTS, MKVARS.LDFLAGS],
                logkey = 'OUT',
            ),
        }

Multi-output builds (ELF → HEX → BIN) — target dict order defines the dependency chain:

    def targets(self):
        return {
            'TARGET':     Target(file='build/app.elf',
                                 script=[MKVARS.LD, '-o', '$@', MKVARS.OBJECTS, MKVARS.LDFLAGS],
                                 logkey='LINK'),
            'TARGET_HEX': Target(file='build/app.hex',
                                 script=['objcopy', '-O', 'ihex', MKVARS.TARGET, '$@'],
                                 logkey='HEX'),
            'TARGET_BIN': Target(file='build/app.bin',
                                 script=[MKVARS.OBJCOPY, '-O', 'binary', MKVARS.TARGET, '$@'],
                                 logkey='BIN'),
        }

Phony targets (flash, format, test…):

    def getPhonyTargets(self):
        return {
            'flash': {
                'deps':   ['all'],
                'logkey': 'FLASH',
                'script': 'openocd -f board/board.cfg -c "program build/app.elf verify reset exit"',
            },
        }

IDE addons — declare as a list attribute instead of a module-level call:

from pymakelib.eclipse_addon import EclipseAddon
from pymakelib.vscode_addon import VSCodeAddon

@Makeclass
class Build(ProjectConfig):
    addons       = [EclipseAddon, VSCodeAddon]
    compiler_set = get_gcc_linux()
    ...

Linker options:

    def linker_opts(self, opts: LinkerOpts) -> LinkerOpts:
        opts.script  = ['-T', 'link.ld']
        opts.machine = ['-mthumb', '-mcpu=cortex-m4']
        opts.libs    = ['-lm', '-lc']
        return opts

Environment variables (.env support)

# pymake/Makefile.py
from pymakelib import ProjectConfig, Makeclass, resolve_env
from pymakelib.toolchain import get_gcc_arm_none_eabi

@Makeclass
class Build(ProjectConfig):
    env_file     = '.env'   # loaded automatically before any get* call
    compiler_set = get_gcc_arm_none_eabi(resolve_env('XC32_PATH', '/opt/xc32/bin/'))
    ...

.env file (not committed to version control):

XC32_PATH=/opt/microchip/xc32/v4.60/bin
PROGRAMMER=PK5

load_dotenv() and resolve_env() are also available for module-level use:

from pymakelib import load_dotenv, resolve_env

load_dotenv()
TOOLCHAIN = resolve_env('TOOLCHAIN_PATH', '/usr/bin/')

Toolchain presets

Function	Description
get_gcc_linux()	Host Linux GCC
get_gpp_linux()	Host Linux G++ (C++)
get_gcc_arm_none_eabi()	ARM bare-metal cross-compiler

All return a CompilerSet dataclass with IDE autocompletion for every tool path.

---

Typed Configuration Reference

All new configuration types live in pymakelib and provide IDE autocompletion.

CompilerOpts

Field	Makefile variable	Example
macros	-D defines	{'DEBUG': None, 'VER': '"2.0"'}
machine	machine/arch flags	['-mthumb', '-mcpu=cortex-m4']
optimize	optimisation	['-O2']
debugging	debug info	['-g3']
preprocessor	preprocessor	['-MP', '-MMD']
warnings	warnings	['-Wall', '-Werror']
standard	language std	['-std=c11']
general	other flags	['--coverage']

Target

Target(
    file   = 'build/app.elf',           # output file path
    script = [MKVARS.LD, '-o', '$@',    # command tokens joined with spaces
               MKVARS.OBJECTS, MKVARS.LDFLAGS],
    logkey = 'LINK',                     # label shown in build output
)

script tokens are joined with a space into one Makefile recipe line. Use && for shell chaining: ['@mkdir -p $(dir $@) &&', MKVARS.LD, ...].

---

For install guide go to install-guide

For more documentation go to Read the Docs