Back to Kindler Main Page

Porting Kindler to a New Platform

Kindler Logo

Guide for adding support for new operating systems and compilers to Kindler.


Table of Contents


Overview

Kindler uses a hint system to adapt to different platforms. Hints are Lua files that describe:

This decoupled design means adding a new platform typically requires writing 1-3 small Lua files.

What You Need

Quick Start

  1. Copy an existing hint file similar to your platform
  2. Modify paths and values for your system
  3. Test with kindler.lua bootstrap
  4. Submit as pull request

Operating System Hints

OS hint files describe system-specific information. Located in hints/os/<osname>.lua

File Naming

The filename must match what uname -s returns (lowercased):

uname -s Output Hint Filename
Linux linux.lua
FreeBSD freebsd.lua
IRIX64 irix65.lua
SunOS solaris.lua
AIX aix.lua

Special case: If uname -s returns multiple values for the same OS family, map them in lib/bootstrap.lua. Example: Both "IRIX" and "IRIX64" map to "irix65".

OS Hint File Structure

-- hints/os/myos.lua

return {
    myos = {
        -- List of available compilers (in order of preference)
        compilers = {"gcc", "clang", "native-cc"},
        
        -- Where to search for libraries
        library_search_paths = {
            "/usr/lib",
            "/usr/local/lib",
            "/opt/pkg/lib",
        },
        
        -- Standard system headers (for fast path checks)
        headers = {
            "unistd.h",
            "sys/types.h",
            "sys/stat.h",
        },
        
        -- Library name mappings
        library_mappings = {
            pthread = {
                shared = {"libpthread.so"},
                static = {"libpthread.a"},
                link_flags = {"-lpthread"},
            },
            zlib = {
                shared = {"libz.so.1", "libz.so"},
                static = {"libz.a"},
                link_flags = {"-lz"},
            },
        },
        
        -- Multi-ABI support (optional, for IRIX-like systems)
        abi_list = {"o32", "n32", "n64"},
        
        -- ABI-specific library locations (optional)
        ["n32.libloc"] = "/usr/lib32",
        ["n64.libloc"] = "/usr/lib64",
    }
}

Field Reference

Field Required Description
compilers Yes Array of compiler names to search for (order matters)
library_search_paths Yes Directories to search for libraries
headers No Common system headers (speeds up config.h generation)
library_mappings No Map library names to actual files and link flags
abi_list No Supported ABIs (only for multi-ABI platforms like IRIX)
<abi>.libloc No ABI-specific library directory

Finding Library Paths

On your target system:

# Find standard library locations
ls -d /usr/lib* /usr/local/lib* /opt/*/lib 2>/dev/null

# Find where libz.so is located
find /usr -name "libz.so*" 2>/dev/null

# Check pkg-config search paths (if available)
pkg-config --variable pc_path pkg-config

# Check what libraries are commonly linked
ldd /bin/ls  # or: otool -L on macOS

Common Library Mappings

Most systems need these:

library_mappings = {
    pthread = {
        shared = {"libpthread.so"},
        link_flags = {"-lpthread"},
    },
    zlib = {
        shared = {"libz.so"},
        link_flags = {"-lz"},
    },
    m = {
        shared = {"libm.so"},
        link_flags = {"-lm"},
    },
    dl = {
        shared = {"libdl.so"},
        link_flags = {"-ldl"},
    },
    ssl = {
        shared = {"libssl.so"},
        link_flags = {"-lssl", "-lcrypto"},
    },
}

Compiler Hints

Compiler hint files describe toolchain capabilities. Located in hints/compiler/<compiler>.lua

File Naming

Use a descriptive name for the compiler:

Compiler Hint File Structure

-- hints/compiler/mycc.lua

return {
    mycc = {
        -- Compiler executables to search for
        ["compiler.drivers"] = {
            "/usr/bin/mycc",
            "/opt/mycc/bin/mycc",
        },
        
        -- Supported languages
        languages = {
            "c89", "c99", "c11",
            "c++98", "c++11",
        },
        
        -- Language-specific settings
        ["c89.driver"] = "mycc",
        ["c89.flags"] = "-std=c89",
        
        ["c99.driver"] = "mycc",
        ["c99.flags"] = "-std=c99",
        
        ["c11.driver"] = "mycc",
        ["c11.flags"] = "-std=c11",
        
        ["c++98.driver"] = "mycc++",
        ["c++98.flags"] = "-std=c++98",
        
        ["c++11.driver"] = "mycc++",
        ["c++11.flags"] = "-std=c++11",
        
        -- Warning flags
        warning_flags = "-Wall -Wextra",
        
        -- Shared library flags
        shared_link_flags = "-shared",
        
        -- ABI flags (optional, for multi-ABI systems)
        ["abi.o32"] = "-mabi=32",
        ["abi.n32"] = "-mabi=n32",
        ["abi.n64"] = "-mabi=64",
        
        -- Version detection (optional)
        version_flag = "--version",
    }
}

Field Reference

Field Required Description
compiler.drivers Yes Paths to search for compiler executable
languages Yes Supported language standards
<lang>.driver Yes Executable name for this language
<lang>.flags No Flags to enable this language standard
warning_flags No Default warning flags
shared_link_flags No Flags for building shared libraries
abi.<name> No ABI-specific compiler flags
version_flag No Flag to display compiler version

Determining Compiler Flags

# Check compiler version
mycc --version
mycc -V

# Test language standard support
mycc -std=c99 test.c  # GCC-style
mycc -xc99 test.c     # Sun CC style

# Check available flags
mycc --help
man mycc

# Test shared library creation
mycc -shared -fPIC -o libtest.so test.c  # GCC
mycc -G -KPIC -o libtest.so test.c       # Sun CC

Common Compiler Patterns

GCC-like compilers (GCC, Clang, ICC):

["c99.driver"] = "gcc",
["c99.flags"] = "-std=c99",
warning_flags = "-Wall -Wextra",
shared_link_flags = "-shared",

Vendor compilers (Sun CC, XL C, MIPSpro):

["c99.driver"] = "cc",
["c99.flags"] = "-xc99",
warning_flags = "-v",
shared_link_flags = "-G",

Compilers with separate C/C++ drivers (MIPSpro):

["c99.driver"] = "c99",    -- Not "cc"
["c++11.driver"] = "CC",   -- Capital CC for C++

Testing Your Port

1. Bootstrap Test

# Run bootstrap
./kindler.lua bootstrap

# Should detect your OS and compilers
# Cache written to ~/.config/kindler/cache/<hostname>.lua

2. Info Check

# Verify detection worked
./kindler.lua info

# Should show:
# - Correct OS name and version
# - Detected compilers
# - Available build tools

3. Simple Project Test

Create test.kindler:

project {
    name = "test";
    lang = "c99";
}

build {
    sources = ["test.c"];
}

Create test.c:

#include <stdio.h>

int main(void) {
    printf("Hello from Kindler!\n");
    return 0;
}

Generate and build:

./kindler.lua generate
make
./test

4. Dependency Test

Test library resolution:

project {
    name = "deptest";
    lang = "c99";
}

dependencies {
    requires = ["pthread", "m"];
}

build {
    sources = ["deptest.c"];
}

Create deptest.c:

#include <stdio.h>
#include <pthread.h>
#include <math.h>

void* thread_func(void* arg) {
    printf("Thread running\n");
    return NULL;
}

int main(void) {
    pthread_t t;
    pthread_create(&t, NULL, thread_func, NULL);
    pthread_join(t, NULL);
    printf("sqrt(2) = %f\n", sqrt(2.0));
    return 0;
}

5. Module Test

Test config.h generation:

project {
    name = "configtest";
    lang = "c99";
}

build {
    sources = ["configtest.c"];
}

config-header {
    output = "config.h";
    platform = "auto";
    check-headers = ["unistd.h"];
    check-functions = ["strlcpy"];
}

modules {
    load = ["config_header"];
}

Submitting Your Port

Before Submitting

Checklist:

What to Include

  1. Hint files: OS and compiler hints
  2. Test results: Output from bootstrap and sample builds
  3. Platform info:
  4. Known issues: Limitations or workarounds

Submission Methods

Option 1: Codeberg Pull Request (preferred)

# Fork repository
# Clone your fork
git clone https://codeberg.org/YourUsername/kindler.git
cd kindler

# Create branch
git checkout -b add-myos-support

# Add your hints
cp myos.lua hints/os/
cp mycompiler.lua hints/compiler/

# Commit
git add hints/
git commit -m "Add support for MyOS with MyCompiler"

# Push and create pull request
git push origin add-myos-support

Option 2: Codeberg Issue

Open an issue and attach the hint files as text or attachments.

Example Commit Message

Add support for AIX 7.2 with XL C compiler

- Added hints/os/aix.lua with library paths for AIX
- Added hints/compiler/xlc.lua with IBM XL C flags
- Tested on AIX 7.2 with XL C 16.1
- All basic tests pass (bootstrap, generate, build)

Known limitations:
- Shared libraries use .a extension (AIX convention)
- Thread support requires -lpthread explicitly

Getting Help

If you get stuck:

Common issues:


Future Improvements

Areas where hint system could be enhanced:

Your feedback and contributions help improve Kindler for everyone!


Copyright 2026 Setsuna Software L.C. and Kazuo Kuroi

Back to Kindler Main Page | Back to Setsuna Software