shmake/README.md

# 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


## Author

Emilia Marigold

## Contact

EmiliaMarigold@protonmail.com