From 5582eac14f92055aa6a17ce330423855734b3c4e Mon Sep 17 00:00:00 2001 From: Noah Swerhun Date: Wed, 13 Dec 2023 15:10:05 -0600 Subject: [PATCH] added readme --- README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..92910c7 --- /dev/null +++ b/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 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 ?