Metadata-Version: 2.4
Name: compiletools
Version: 8.1.1
Summary: Tools to make compiling C/C++ projects easy
Keywords: c++,make,development
Author: DrGeoff
Author-email: DrGeoff <drgeoffathome@gmail.com>
License-Expression: GPL-3.0-or-later
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: configargparse>=1.5.3
Requires-Dist: appdirs>=1.4.4
Requires-Dist: psutil>=5.9.0
Requires-Dist: rich>=12.0.0
Requires-Dist: rich-rst>=1.1.7
Requires-Dist: stringzilla>=3.0.0
Requires-Dist: bump-my-version>=0.26.0 ; extra == 'dev'
Requires-Dist: twine>=5.0.0 ; extra == 'dev'
Requires-Dist: pytest>=8.1.1 ; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5 ; extra == 'dev'
Requires-Dist: ruff>=0.14.0 ; extra == 'dev'
Requires-Dist: pyright>=1.1 ; extra == 'dev'
Requires-Dist: pre-commit>=4.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=6.0 ; extra == 'dev'
Requires-Dist: textual>=0.40.0 ; extra == 'dev'
Requires-Dist: textual>=0.40.0 ; extra == 'tui'
Requires-Python: >=3.10
Project-URL: Download, https://github.com/DrGeoff/compiletools/archive/v{version}.tar.gz
Project-URL: Homepage, http://drgeoff.github.io/compiletools/
Provides-Extra: dev
Provides-Extra: tui
Description-Content-Type: text/x-rst

.. image:: https://github.com/DrGeoff/compiletools/actions/workflows/main.yml/badge.svg
    :target: https://github.com/DrGeoff/compiletools/actions
    :alt: Build Status

============
compiletools
============

--------------------------------------------------------
C/C++ build tools that requires almost no configuration.
--------------------------------------------------------

:NOTE: The repository-level ``README.rst`` is a symlink to this file, so they
       are the same canonical document.

:Author: drgeoffathome@gmail.com
:Date:   2025-12-17
:Version: 8.1.1
:Manual section: 1
:Manual group: developers


SYNOPSIS
========
    ct-* [compilation args] [filename.cpp] [--variant=<VARIANT>]

DESCRIPTION
===========
compiletools provides C/C++ build automation with minimal configuration. The tools
automatically determine source files, dependencies, and build requirements by
analyzing your code.

To build a C or C++ project, simply type:

.. code-block:: bash

    ct-cake

This automatically determines source files, builds executables, and runs tests.
See ct-cake(1) for details.

QUICK START
===========

Try compiletools without installing using uvx:

.. code-block:: bash

    uvx --from compiletools ct-cake
    uvx --from compiletools ct-compilation-database

This runs tools directly without affecting your system. All ct-* tools work
with uvx (e.g., ``uvx --from compiletools ct-config``).

INSTALLATION
============

.. code-block:: bash

    uv pip install compiletools

Or for development:

.. code-block:: bash

    git clone https://github.com/DrGeoff/compiletools
    cd compiletools
    uv pip install -e ".[dev]"

KEY FEATURES
============

**Magic Comments**
    Embed build requirements directly in source files using special comments
    like ``//#LDFLAGS=-lpthread`` or ``//#PKG-CONFIG=zlib``. See ct-magicflags(1).

**Automatic Dependency Detection**
    Traces #include statements to determine what to compile and link.
    No manual dependency lists needed.

**Build Variants**
    Support for debug, release, and custom build configurations.
    Use ``--variant=release`` to select. See ct-config(1).

**Pluggable Build Backends**
    Choose from Make (default), Ninja, CMake, Bazel, Tup, or the builtin
    Shake backend.  Distribute compilation across an HPC cluster with the
    Slurm backend.  Use ``--backend=<name>`` to select.  See ct-backends(7).

**File Locking**
    Multi-user/multi-host object file caching with filesystem-aware locking
    for faster builds in team environments. Enable with ``file-locking = true``.

**Minimal Configuration**
    Works out-of-the-box with sensible defaults. Configuration only needed
    for customization.

CORE TOOLS
==========

**ct-cake**
    Main build tool. Auto-detects targets, builds executables, runs tests.

**ct-compilation-database**
    Generate compile_commands.json for IDE integration. Auto-detects targets.

**ct-config**
    Inspect configuration resolution and available compilation variants.

**ct-magicflags**
    Show magic flags extracted from source files.

**ct-headertree**
    Visualize include dependency structure.

**ct-filelist**
    Generate file lists for packaging and distribution.

**ct-timing-report**
    Analyze build timing data from ``ct-cake --timing``.  Interactive TUI,
    static summary, run comparison, and Chrome Trace export.

**ct-cleanup-locks**
    Clean stale locks from file locking.

**ct-list-backends**
    List available build backends (make, ninja, cmake, bazel, shake, tup).

**Shell Wrappers**
    Convenience scripts in ``scripts/``: ct-build, ct-build-static-library,
    ct-build-dynamic-library, ct-watch-build, ct-lock-helper, ct-release.

CONFIGURATION
=============
Options are parsed using ConfigArgParse, allowing configuration via command line,
environment variables, or config files.

Configuration hierarchy (lowest to highest priority):

* Executable directory (ct/ct.conf.d alongside the ct-* executable)
* System config (/etc/xdg/ct/)
* Python virtual environment (${python-site-packages}/ct/ct.conf.d)
* Package bundled config (<installed-package>/ct.conf.d)
* User config (~/.config/ct/)
* Project config (<gitroot>/ct.conf.d/)
* Git repository root directory
* Current working directory
* Environment variables (capitalized, e.g., VARIANT=release)
* Command-line arguments

Build variants (debug, release, etc.) are config profiles specifying compiler and
flags. Common variants include blank (default debug), blank.release, gcc.debug,
gcc.release, clang.debug, clang.release.

Common usage:

.. code-block:: bash

    ct-cake --variant=release
    ct-cake --append-CXXFLAGS="-march=native"

For details on configuration hierarchy, file format, and variant system, see ct-config(1).

ATTRIBUTION
===========
This project is derived from the original compiletools developed at Zomojo Pty Ltd
(between 2011-2019). Zomojo ceased operations in February 2020. This repository
continues the development and maintenance of the compiletools project.

SEE ALSO
========
* ct-backends (7) -- build backend architecture and selection guide
* ct-build
* ct-build-dynamic-library
* ct-build-static-library
* ct-cake
* ct-cleanup-locks
* ct-compilation-database
* ct-config
* ct-cppdeps
* ct-create-makefile
* ct-filelist
* ct-findtargets
* ct-git-sha-report
* ct-gitroot
* ct-headertree
* ct-jobs
* ct-list-backends
* ct-list-variants
* ct-lock-helper
* ct-magicflags
* ct-release
* ct-timing-report
* ct-watch-build
