added readme

This commit is contained in:
Noah Swerhun 2023-12-13 15:10:05 -06:00
parent c4d2ec2529
commit 5582eac14f

95
README.md Normal file
View file

@ -0,0 +1,95 @@
# mgen
Makefile generator for C projects.
## Overview
`mgen` automatically generates build rules for all source files (extension `.c`)
it finds in a recursive search of the directory in which it is run. It places
the rules in your existing makefile, meaning you can easily change build options
and even write your own rules based on those generated.
`mgen` will place the generated rules between the strings "`#=mgen_start=#`" and
"`#=mgen_end=#`" in your makefile. If these lines are not present, it will add
them to the end of the file and place the rules there. Anything not between
these lines will not be touched by `mgen`.
`mgen` utilizes make variables when generating the build rules. Some of these
variable names are common, while others are specific to `mgen`.
These are:
- CC -> C compiler
- CFLAGS -> compilation flags
- LDLIBS -> linker libraries
- LDFLAGS -> linker flags
- TARGET -> name of final executable/library
- BUILDDIR -> the directory where the final executable/library will be placed
- OBJDIR -> the directory where compiled object files will be placed
- INCS -> place for `-I` compiler flags to specify include directories. (must
be placed in this variable, not in CFLAGS or elsewhere)
It is therefore recommended that you set these at the beginning of your
makefile, unless you want to use the `make` defaults.
`mgen` will set `BUILDDIR` by default to `./build`. `OBJDIR` will be set to
`BUILDDIR/obj`. The user may manually override either or both of these variables
themselves.
## Why use this tool?
`mgen` offers distinct advantages over other, more complex build systems. These
include:
1. **Simplicity.** There are no special languages to learn, extra configuration
files, and countless features that you won't ever use. Of course, if you need
those things, there are other options available; that is not the space `mgen`
intends to occupy.
1. **Extensibility.** Because `mgen` adds to your existing makefile, you can
write your own build rules in a language you already know: make. Your custom
rules can use the ones generated by `mgen`, or you can just use the generated
ones; it's up to you, `mgen` gives you that option.
1. **Portability.** Once the makefile is generated, it can be run on any machine
that runs `make`. Your users do not have to have `mgen` to compile your
program, they can just use the generated makefile.
## Usage
```
$ mgen --help
Usage: mgen [OPTIONS]
Options:
-p, --pretty Replace default make output with nice build messages (colors!)
-c, --clean Generate a 'clean' rule that removes all build files
-r, --run Generate a 'run' rule that allows you run the executable with 'make run'
-l, --library Configure build rule to create a library rather than an executable (NYI)
-m, --makefile <MAKEFILE> Path to makefile [default: ./Makefile]
-h, --help Print help
```
Starting from a "blank slate," i.e. you have no build system configured in your
project, simply run `mgen` in the root directory and then run `make`. It's as
easy as that.
If you already have a makefile in use, remove any rules to build the target or
object files (that's what `mgen` is for). You can keep any other, more complex
rules that depend on these things, though. Then, run `mgen` and `make` and you
are good to go.
## Build Instructions
Build: `cargo build --release`
Install (must build first) (needs root): `sh install.sh`
Uninstall (needs root): `sh uninstall.sh`
## Todo
- Add functionality to generate rules to build a library, as opposed to an
executable.
- Add exclude directory(ies) from search
- Eventually: write man page.
- Maybe: figure out a way to only have the user run `mgen` once, then the
makefile itself will call it again if it needs to be regenerated due to a
change in project structure ?