From 62f81dfc06cb143f078590089cb620978d1cddd8 Mon Sep 17 00:00:00 2001 From: epochryphon Date: Tue, 26 May 2026 15:16:04 -0500 Subject: [PATCH] updated readme --- README.md | 270 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 266 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a03b50c..66cd725 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,270 @@ -shmake build/project scaffolding system. +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 -shmake (simple helpful make) or (shell make) +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 -A POSIX compliant build/project management system meat for C projects. +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) -It uses pure sh and generate POSIX compliant makefiles currently in alpha and often gets non-working/breaking updates pushed \ No newline at end of file +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 ` - Project name (required) +- `--compiler ` - C compiler (default: gcc) +- `--c-standard ` - C standard (default: C11) +- `--strictness <0|1|2|3>` - Compiler strictness level (default: 2) +- `--test-lib ` - Test library (default: None) +- `--license ` - License type (default: MIT) +- `--vcs ` - Version control (default: git) +- `--targets ` - Build targets (default: linux) +- `--resources ` - 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:** +```sh +# 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 ` - Create a new module +- `library ` - Add external library +- `link ` - Add system libraries + +**Library Options:** +- `--dest ` - 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:** +```sh +# 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:** +```sh +# 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_/ +│ ├── .h +│ ├── .c +│ ├── internal/ +│ │ ├── _internal.h +│ │ └── _internal.c +│ └── tests/ +│ ├── _test.h +│ └── _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. + +```sh +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