@@ 1,4 1,50 @@
# cod
## Compile on demand
-It does that.
+cod is a source "package manager" based on makepkg, pacman, and asp. It's
+really just a shell script that fetches sources from the Arch Build System and
+keeps them organized for you. What makes it interesting is that it also
+maintains a symlink farm based on the binaries that pacman knows about from
+the installed packages. All of them link to `codstub`, an even smaller shell
+script which recognizes which binary you're trying to run and runs the `build`
+step of the package's PKGBUILD on the fly before launching the binary.
+
+This may have buried the lede a bit, so TL;DR: **cod allows you to edit your
+tools in real time.** You never have to think about which build system they
+use, or where to put the binaries.
+
+This is made tolerable by the fact that modern build systems tend to be aware
+of what has changed since the last build. If the source is the same, the
+overhead added by cod is equal to the time it takes the build system of the
+package to start up and determine there's nothing to do. This of course varies
+quite a bit, but there's nothing we can do about that.
+
+## Use
+
+Set your CODPATH (it defaults to /opt/cod), and make sure you can write to it.
+Add $CODPATH/bin to your $PATH to make the experience seamless, but this is
+technically optional.
+
+`codinstall <package>`. That's it. When you run the program you installed for
+the first time it will be compiled from scratch, so it will likely be quite
+slow. Subsequent runs should be nearly the same as running the binary directly.
+
+## Status
+
+This is a toy, but it does what it says on the tin. It was written on a whim
+to play with the idea. Whether it's actually useful is debatable.
+
+It currently assumes that your pacman file database is up to date, in order
+to avoid ever needing to escalate privileges. If it breaks, try `pacman -Fy`.
+
+## Potential enhancements
+
+cod currently only works on binaries. While you can install the sources for
+libraries, it doesn't know to use this copy of the library to build other
+packages that depend on it. There's nothing preventing this from being added,
+though! It would need to do some ld magic when executing the programs in case
+of static linking as well…
+
+It would also be smart to add an option to immediately build installed
+packages, instead of waiting to do it the first time you run one of the
+binaries.