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