Update README.md
This commit is contained in:
115
README.md
115
README.md
@@ -1,102 +1,25 @@
|
||||
# makemake
|
||||
**makemake** is a pure POSIX-compliant (`.POSIX`), multi-threaded build template for C projects. It utilizes a dynamic build graph generator, requires zero GNU or BSD extensions, and runs natively on any standard UNIX shell (`/bin/sh`).
|
||||
|
||||
This repository contains a makefile for C projects. It is configured out-of-the-box for **C17** using **GCC**, enforces extremely strict compilation standards (treating all warnings as errors), manages out-of-source builds, and includes automatic dependency tracking and versioning.
|
||||
**Quick Start**
|
||||
|
||||
## Setup Tutorial
|
||||
* Place `.c` files in `source_code/` and `.h` files in `includes/`.
|
||||
* Run `make init` once to bootstrap the project layout.
|
||||
* Run `make -j8 debug` to compile incrementally and in parallel.
|
||||
|
||||
Follow these steps to bootstrap your project from scratch using this Makefile:
|
||||
**Make Targets**
|
||||
|
||||
### 1. Initialize the Project
|
||||
| Target | Description |
|
||||
| --- | --- |
|
||||
| `make` / `make help` | Prints basic usage instructions and target overviews. |
|
||||
| `make init` | Creates required project directories (`source_code`, `includes`, `output`, `config`) and starter templates. |
|
||||
| `make debug` | Dynamically builds a parallel-safe dependency graph and compiles using `DEBUG_FLAGS` (`-g3`, `-O0`, UBSan). |
|
||||
| `make fast` | Compiles an optimized release build using `RELEASE_FLAGS` (`-O2`, `-s`, `NDEBUG`) without modifying the version string. |
|
||||
| `make release` | Bumps the version using an automated timestamp (`_YY.DAY.HH.MMSS`) and compiles an optimized release binary. |
|
||||
| `make clean` | Wipes the `output/` directory and temporary build scripts inside `config/`. |
|
||||
|
||||
Place the `Makefile` in the root of your new (and empty) project directory. Note that the output executable will be named after your root directory.
|
||||
Run the following command to scaffold the required directory structure:
|
||||
**Customization Guide**
|
||||
|
||||
```bash
|
||||
make init
|
||||
|
||||
```
|
||||
|
||||
**What this does:** Creates the `config/`, `includes/`, `output/`, and `source_code/` directories. It also generates a starter `main.c` and initializes the versioning and file list configuration files.
|
||||
|
||||
### 2. Write Your Code
|
||||
|
||||
* Place all your `.c` files inside the `source_code/` directory (or subdirectories within it).
|
||||
* Place all your `.h` files inside the `includes/` directory.
|
||||
|
||||
### 3. Synchronize the Build System
|
||||
|
||||
Whenever you **add, rename, or delete** a `.c` or `.h` file, you must tell the Makefile to update its tracking lists:
|
||||
|
||||
```bash
|
||||
make synch
|
||||
|
||||
```
|
||||
|
||||
**What this does:** Scans your directories and updates `config/source_code_list` and `config/header_list`.
|
||||
|
||||
### 4. Build the Project
|
||||
|
||||
Compile your code for the first time in debug mode:
|
||||
|
||||
```bash
|
||||
make debug
|
||||
|
||||
```
|
||||
|
||||
Your compiled executable will be located in the `output/` directory, named `<your_folder_name>_00.000.00.0000` (or whatever the current version string is).
|
||||
|
||||
## Project Structure
|
||||
|
||||
After running `make init` and building, your project will look like this:
|
||||
|
||||
```text
|
||||
my_project/ # Root folder (dictates the executable name)
|
||||
├── Makefile # The build script
|
||||
├── config/ # Build tracking files (auto-generated)
|
||||
│ ├── header_list
|
||||
│ ├── source_code_list
|
||||
│ └── version
|
||||
├── includes/ # Place all your .h files here
|
||||
├── source_code/ # Place all your .c files here
|
||||
│ └── main.c
|
||||
└── output/ # Build artifacts (ignored by git ideally)
|
||||
├── obj_debug/ # .o and .d files for debug builds
|
||||
├── obj_release/ # .o and .d files for release builds
|
||||
└── my_project_version # The final compiled executables
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration & Defaults
|
||||
|
||||
This Makefile is heavily configured for safety and strictness. Here is how to modify the defaults to suit your needs:
|
||||
|
||||
### 1. Changing the C Standard
|
||||
|
||||
The project defaults to **C17**. To change this to C11, C99, or C2x:
|
||||
|
||||
* Open the `Makefile`.
|
||||
* Locate the `CFLAGS = -std=c17 \` line.
|
||||
* Change `-std=c17` to `-std=c11` (or your preferred standard).
|
||||
|
||||
### 2. Changing the Compiler
|
||||
|
||||
The default compiler is **GCC**. To use Clang (which is highly recommended for macOS users or for its excellent static analyzer):
|
||||
|
||||
* Locate `CC = gcc` at the top of the file.
|
||||
* Change it to `CC = clang`.
|
||||
|
||||
### 3. Modifying Warning Strictness (Fixing Compilation Blocks)
|
||||
|
||||
By default, this Makefile includes `-Werror`, which **treats all warnings as errors** and halts compilation. It also includes an extensive list of strict warnings (like `-Wconversion`, `-Wshadow`, `-Wpadded`, etc.).
|
||||
|
||||
* **To allow warnings to pass without failing the build:** Remove the `-Werror \` line from the `CFLAGS` block.
|
||||
* **To remove specific strict checks:** Simply delete or comment out the specific flag (e.g., `-Wmissing-prototypes \`) from the `CFLAGS` list.
|
||||
|
||||
### 4. Modifying Debug and Release Flags
|
||||
|
||||
You can tweak optimization levels and sanitizers at the top of the file:
|
||||
|
||||
* **Debug (`DEBUG_FLAGS`):** Defaults to `-g3 -O0 -fsanitize=undefined -fno-omit-frame-pointer`. You can add Address Sanitizer by replacing `undefined` with `address`. (after the `-fsanitize=` flag)
|
||||
* **Release (`RELEASE_FLAGS`):** Defaults to `-O2 -D NDEBUG`. (`NDEBUG` strips out `assert()` calls). If you want maximum optimization, you can change `-O2` to `-O3` or `-Ofast` (use `-Ofast` with caution as it breaks strict IEEE compliance for math).
|
||||
* **How to change the compiler:** Edit the `CC = gcc` variable at the top of the file to use `clang` or other compilers.
|
||||
* **How to change the C standard being used:** Locate `CFLAGS` and modify `-std=c17` to your preferred standard (e.g., `-std=c11`, `-std=c99`) etc.
|
||||
* **Modifying Warning Strictness:** Add, or remove specific flags within the `CFLAGS` block. Removing `-Werror` will allow compilation to continue past warnings.
|
||||
* **Linking External Libraries (e.g., Raylib):** Locate the `debug`, `fast`, and `release` targets in the Makefile. Find the final linking step (`$(CC) $(CFLAGS) ... -o $$OUT $$OBJS`) and append your static library paths or system link flags (e.g., `-lraylib -lGL -lm -lpthread -ldl -lrt -lX11`).
|
||||
Reference in New Issue
Block a user