kmake/README.md

# kmake

Kitty Make - A modern, flexible build automation application written in C++.

## Overview

kmake is a build automation tool designed to simplify the compilation and linking process for C/C++ projects. It uses a declarative YAML configuration file (`kmake.yml`) to define build parameters, targets, and per-platform/distro build commands.

## Features

- **Declarative Configuration**: Define builds in `kmake.yml` using YAML
- **Multi-platform Support**: Configure different build commands per distro/platform
- **Parallel Compilation**: Multi-threaded compilation with configurable thread count
- **Dependency Tracking**: Automatic dependency generation and tracking
- **Variable Substitution**: Use `{placeholders}` in commands for dynamic values
- **Distro-specific Overrides**: Override global settings per distribution

## Configuration (`kmake.yml`)

```yaml
name: ''                    # Project name
author: ''                  # Primary author
authors: ['']               # List of authors
descr:
  - ''                      # Project description (multi-line)
verbosity: normal           # debug, high, normal, low

build:
  src:
    path: './src'           # Source directory
    targets: ['c','cpp']    # File extensions to compile
  out:
    path: './out'           # Output directory
    target: 'exe'           # Final output extension
  bin:
    path: './bin'           # Object files directory
    target: 'o'             # Object file extension
  deps:
    path: './bin'           # Dependency files directory
    target: 'd'             # Dependency file extension
    rev_target: 'rd'        # Reverse dependency extension
    style: gcc              # Dependency generation style (gcc/msvc)
  threads: 4                # Parallel compilation threads (0 = disabled)

vars:                       # Global variables for placeholder substitution
  key: value

distros:                    # Per-distro/platform configuration
  distro_name:
    vars: {}                # Override global variables
    start: []               # Commands run before build
    deps: []                # Dependency generation commands
    compile: []             # Per-file compilation commands (parallel)
    link: []                # Linking commands
    end: []                 # Post-build commands
```

## Variable Placeholders

Use `{placeholder}` syntax in commands for dynamic substitution:

- `{src_file}` - Current source file path
- `{obj_file}` - Current object file path
- `{obj_files}` - All object files (space-separated, link phase only)
- `{dep_file}` - Current dependency file path
- `{rv_dep_file}` - Reverse dependency file path
- `{out}` - Output executable path
- `{bin}` - Binary/object directory
- `{include}` - Include directories
- `{cflags}` - Compiler flags
- `{ldflags}` - Linker flags
- Custom variables from `vars` and `distros.*.vars`

## Build Phases

1. **start** - Setup commands (create directories, etc.)
2. **deps** - Generate dependency files for each source file
3. **compile** - Compile each source file to object file (parallelizable)
4. **link** - Link object files into final executable
5. **end** - Cleanup, packaging, testing commands

## Example: Linux GCC Distro

```yaml
distros:
  linux-gcc:
    vars:
      cflags: '-Wall -Wextra -O2'
      ldflags: ''
    start:
      - 'mkdir -p {bin} {out}'
    deps:
      - 'gcc {cflags} -MM -MG -MP -MT {obj_file} -MF {dep_file} {src_file}'
    compile:
      - 'gcc {cflags} -c {src_file} -o {obj_file}'
    link:
      - 'gcc {ldflags} -o {out} {obj_files}'
    end:
      - 'echo "Build complete: {out}"'
```

## Example: Windows MSVC Distro

```yaml
distros:
  windows-msvc:
    vars:
      cflags: '/W4 /O2'
      ldflags: ''
    start:
      - 'if not exist {bin} mkdir {bin}'
      - 'if not exist {out} mkdir {out}'
    deps:
      - 'cl {cflags} /showIncludes {src_file} 2>nul | findstr /R "^Note: including file:" > {dep_file}'
    compile:
      - 'cl {cflags} /c {src_file} /Fo{obj_file}'
    link:
      - 'link {ldflags} /OUT:{out} {obj_files}'
    end:
      - 'echo Build complete: {out}'
```

## Usage

```bash
# Build with default distro
kmake

# Build with specific distro(s)
kmake linux-gcc windows-msvc

# Set verbosity (debug, high, normal, low)
kmake -verbosity normal

# Show version
kmake -version

# List available distros
kmake -list

# Print project description and authors
kmake -descr
```

## Architecture

- **Project** - Parses and holds `kmake.yml` configuration
- **Distro** - Per-platform build command sets with variable overrides
- **Executor** - Runs command sequences (serial per phase, parallel for compile)
- **Variables** - Global and per-distro variable resolution with placeholders

## Requirements

- C++17 compatible compiler
- CMake 3.16+
- ckitty library
- desktoplib library

## Building

```bash
mkdir build && cd build
cmake ..
make -j4
```

## License

MIT License