shmake/README.md

The user wants to brainstorm the design of shmake. They want:

1. A spec-style README with examples
2. No BUILD_MODE variable - instead use make test, make debug, make release
3. init should take flags but fall back to interactive mode if flags are missing
4. VCS awareness when pulling libraries (git vs tar/zip with wget/curl)
5. Compiler strictness settings (0=none, 1=basic/pedantic, 2=standard/default+werror+wextra, 3=maximum)
6. Everything in POSIX sh and POSIX make
7. Commands: init, add, sync (maybe others?)
8. Manual modes for automation

Let me think about the full design:

Commands needed:

• shmake init [flags] - initialize project, interactive if flags missing
• shmake add [type] [name/url] [options] - add modules or libraries
• shmake sync - regenerate Makefile from .conf files
• shmake link [libs] - add system libraries (already exists)
• shmake help - show help

For the add command, they want to specify where libraries go:

• shared_libraries (normal)
• debug_only (debug/logging libraries)
• test_only (test libraries)
• release_only (release-only libraries)

Compiler strictness:

• 0: none
• 1: basic (pedantic, -Wall)
• 2: standard (default, includes -Werror, -Wextra)
• 3: maximum (includes more warnings)

VCS detection:

• .git URLs → git clone
• .tar.gz, .zip, etc → wget/curl + extract

Let me write a comprehensive spec-style README.

shmake: Simple Helpful Make (Shell Make)

A POSIX-compliant build and project management system for C projects. All scripts use pure POSIX sh. Generated Makefiles are fully POSIX-compliant and work with GNU Make, bmake, and BSD Make.

Philosophy

shmake is designed to be maximally portable. No bashisms, no GNU extensions. The goal is a build system that works on any POSIX system with a C compiler and make.

Commands

shmake init [flags]

Initialize a new project. Accepts flags for automation. If required flags are missing, drops into interactive CLI mode.

Flags:

• --name <name> - Project name (required)
• --compiler <gcc|clang|tcc|cc> - C compiler (default: gcc)
• --c-standard <C99|C11|C17|C23> - C standard (default: C11)
• --strictness <0|1|2|3> - Compiler strictness level (default: 2)
• --test-lib <Unity|Check|CMOCKA|None> - Test library (default: None)
• --license <license-name> - License type (default: MIT)
• --vcs <git|hg|svn|fossil|bzr|darcs|none> - Version control (default: git)
• --targets <list> - Build targets (default: linux)
• --resources <list> - Resource subdirectories (optional)

Strictness Levels:

• 0 - No extra warnings
• 1 - Basic: -Wall -pedantic
• 2 - Standard: -Wall -Wextra -Werror -pedantic (default)
• 3 - Maximum: -Wall -Wextra -Werror -pedantic -Wconversion -Wshadow -Wcast-align -Wstrict-prototypes

Examples:

# Fully automated init
shmake init --name myproject --compiler clang --c-standard C17 --strictness 2 --license MIT --vcs git

# Interactive (missing flags)
shmake init --name myproject
# Prompts for compiler, standard, strictness, license, etc.

# Minimal (all interactive)
shmake init

shmake add [options]

Add modules or external libraries to the project.

Types:

• module <name> - Create a new module
• library <url> - Add external library
• link <libs> - Add system libraries

Library Options:

• --dest <shared|debug_only|test_only|release_only> - Destination directory (default: shared)

VCS Detection:

• .git URLs → uses git clone
• .tar.gz, .tar.bz2, .zip → uses wget or curl to download, then extracts to correct directory

Examples:

# Add a module
shmake add module my_feature

# Add a library to shared_libraries
shmake add library https://github.com/user/repo.git

# Add a library to test_only
shmake add library https://github.com/ThrowTheSwitch/Unity.git --dest test_only

# Add a tarball library
shmake add library https://example.com/lib.tar.gz --dest shared

# Add system libraries
shmake add link X11 pthread m

shmake sync

Scan source directories and regenerate Makefile configurations based on .conf files in shmake_config/. Detects source files, include paths, and linked libraries automatically.

Examples:

# Sync after adding source files
shmake sync

# Sync after adding libraries
shmake add library https://github.com/user/repo.git
shmake sync

shmake help

Show help message with all commands and options.

Project Structure

project/
├── source_code/
│   ├── main.c
│   └── MODULE_<name>/
│       ├── <name>.h
│       ├── <name>.c
│       ├── internal/
│       │   ├── <name>_internal.h
│       │   └── <name>_internal.c
│       └── tests/
│           ├── <name>_test.h
│           └── <name>_test.c
├── external_code/
│   ├── shared_libraries/
│   │   ├── source_code/
│   │   └── binary/
│   ├── debug_only/
│   │   ├── source_code/
│   │   └── binary/
│   ├── test_only/
│   │   ├── source_code/
│   │   └── binary/
│   └── release_only/
│       ├── source_code/
│       └── binary/
├── resources/
│   ├── fonts/
│   ├── images/
│   └── ...
├── build_output/
├── intermediate_code/
├── shmake_config/
│   ├── project.conf
│   ├── makefile.conf
│   ├── makefile_test.conf
│   ├── makefile_debug.conf
│   ├── makefile_release.conf
│   ├── makefile_clean.conf
│   └── linked.conf
├── LICENSE
├── README.md
├── Makefile
└── .gitignore (or .hgignore, .svnignore, etc.)

Build Targets

shmake generates separate Makefile targets for each build mode. No BUILD_MODE variable needed.

make          # Release build (default)
make debug    # Debug build with -g -O0
make test     # Test build with test libraries
make release  # Explicit release build
make clean    # Clean build artifacts
make distclean # Clean including intermediate files

Configuration Files

shmake_config/project.conf

Stores project metadata:

PROJECT_NAME=myproject
COMPILER=clang
C_VERSION=c17
STRICTNESS=2
TEST_LIB=Unity
LICENSE=MIT
VCS=git
VERSION=26.146.1448
ENABLED_TARGETS= linux
ENABLED_RESOURCES= fonts images

shmake_config/linked.conf

Stores system library flags:

LINKED_LIBS = -lX11 -lpthread -lm

shmake_config/makefile.conf

Base configuration with compiler flags, include paths, and shared library paths.

shmake_config/makefile_debug.conf

Debug-specific flags: -g -O0 -DDEBUG

shmake_config/makefile_release.conf

Release-specific flags: -O2 -DNDEBUG

shmake_config/makefile_test.conf

Test-specific configuration with test library paths.

POSIX Compliance

Shell Scripts

All scripts use #!/bin/sh and avoid:

• Bash arrays
• [[ conditionals
• (( )) arithmetic
• Process substitution <()
• Bash-specific parameter expansion ${var//pattern/replacement}

Makefiles

Generated Makefiles use:

• .POSIX: directive for bmake compatibility
• .include instead of include for bmake
• No GNU Make-specific functions
• Standard variable syntax only

License

shmake is licensed under AGPL-3.0. All generated projects use the license specified during initialization.

Version

Current version: 0.1.0-alpha

Author

Emilia Marigold

Contact

Marigold Computer Labs LLC