updated readme
This commit is contained in:
270
README.md
270
README.md
@@ -1,8 +1,270 @@
|
||||
shmake build/project scaffolding system.
|
||||
<think>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
|
||||
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.
|
||||
</think>
|
||||
|
||||
# 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:**
|
||||
```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 <type> <name> [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:**
|
||||
```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_<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.
|
||||
|
||||
```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
|
||||
|
||||
Reference in New Issue
Block a user