added readme

README.md

@@ -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 ?