|                                                         |
|  [gofr] Go Object File Rebuilder                        |
|     by: Kyle Lemons                                     |
|     (C) 2010 - BSD License                              |
|                                                         |

1. Installation

NOTE: This package requires `goopt`: goinstall -u github.com/droundy/goopt
      The automated installer will attempt to install/update it for you.
      If for some reason that doesnt work, try github.com/kylelemons/goopt
      and change the include in cmd/gofr.go to reflect that change.

> hg clone http://bitbucket.org/kylelemons/gofr
> cd gofr && bash INSTALL.sh && cd -

You should see a message stating that "All tests passed!" and that "Install succeeded!"

2. Usage

  Usage of ./gofr:
    -o        --binary         Name of binary (if not specified, will be file including main)
    -v        --verbose        Show commands as they are executed
    -V        --vverbose       Show very verbose debugging information
    -p        --pretend        Dont actually execute any commands (use with -v to see what would be executed
    -c        --clean          Remove the object, test, and library directories
    -f        --format         Format go source files if they do not adhere to gofmt rules
    -F        --no-format      Disable auto-formatting (the default)
    -x regex  --ignore=regex   Specify regular expressions of file paths to ignore (eXclude) (can specify multiple times)
    -l lib    --libs=lib       CGO Libraries (can specify multiple times)
    -I pkg    --install=pkg    Enable installation of the .a files and binaries into GOROOT and GOBIN under pkg/
    -P *      --prefix=*       Specify the installation prefix for the .a files (defaults to ${GOROOT}/pkg/${GOOS}_${GOARCH}/${PKG})
    -B *      --bin-prefix=*   Specify the installation prefix for the binaries (defaults to ${GOBIN}/${PKG})
    -O _obj   --objdir=_obj    The directory to put object files into
    -T _test  --testdir=_test  The directory to put test files into
              --version        Print version information and exit
              --help           show usage message

*** CGO is currenly broken ***

  When gofr is run, it will process all .go files in the current subtree.  In
a given directory, all files with the same package will be compiled together and
linked.  The output objects will go into (by default) the _obj directory with
the same relative path as the package itself.  The proper inclusion options are
specified to the compiler and linker such that any local packages can be
included directly.  If there is a util package in the base directory, it can be
imported as "util", and if there is a driver package in the cgo subdirectory, it
can be included as "cgo/driver".
  If gofr finds a "C" include in any package, it marks that package as a cgo
package for special processing.  It builds all .c files that have a
corresponding .h file (by prefix) included in the doc comment before that import
into the dynamic library along with any libraries specified by the --libs
option.  For cgo to work, GOOS and GOARCH must be set.
  Includes are processed and treated to be local to the directory in which the
go file including them resides, so in a subdirectory an include of "sub/pkg"
will be in the sub subdirectory of the current subdirectory.
  To automatically install the application (and all generated binaries and
libraries), invoke the '--install' option with the name of the package.  For

# gofr --install=mylib.googlecode.com/hg

  The above command will compile everything (in this case, log4go is a library,
so it will generate .a files) and copy them to the appropriate directories.  For
the sake of illustration, in the following explanations, ${PKG} represents the
package that is provided to '--install' (and should be a fully qualified path
similar to what would be provided by goinstall). Unlike goinstall, this path is
simply the directory into which the libraries are installed, it is not the
qualified name of the package, so in the above instance a package named "mylib"
in the root directory would be imported in other programs as
"mylib.googlecode.com/hg/mylib". For binaries, this directory is either
${GOBIN}/${PKG} if no '--bin-prefix' is specified or whatever directory is given
to that option.  Similarly, for libraries, the directory would be set to
${GOROOT}/pkg/${GOOS}_${GOARCH}/${PKG} unless a different '--prefix' is given.
  When installing, subdirectories are always preserved in the installed
directory structures.
  When installing an application (with no subdirectory binaries), you may want
to override the --bin-prefix so that the application becomes immediately
available to users, for example: (this assumes your GOBIN is set)

# gofr --install=gofr.kylelemons.googlecode.com --bin-prefix=${GOBIN}

  Assuming gofr does not have any libraries to install, the ${PKG} will actually
not be used in any installation paths, but should probably be kept in the
command line just in case (especially if it is in a script or makefile).
  Note that it is generally not recommended to override the setting for --prefix
unless you really know what you are doing... all of the libraries are available
in the --objdir/--libdir if you need to look at them, and the standard --prefix
will allow other packages to include the ones that you are installing.
  When building a library, it is highly recommended that you use the --format
options to ensure that everything is formatted according to the gofmt rules.

3. Building an Application
  An application will be built if gofr finds a main package, and it will be
linked to a binary named after the file containing main() or whatever is
specified on the command line.  If this main package is found in the root
directory, then it will suppress the generation of .a files.  Any main packages
in subdirectories will also be linked into binaries based on the name of the
file containing their main() functions or a binary name from the command-line.
  With multiple binaries, it is usually a good idea to check to make sure gofr
is doing what you intend, at least the first time.  Run with -v and -p, and make
sure the commands look correct.  Let me know (see the contact section) if you
see anything that looks weird.

4. Building a Library
  A directory will be built into a series of libraries if no main package is
found in the root directory. Binaries will still be built in subdirectories as
appropriate. Each library will have a corresponding .a file archived into the
object directory.
  CGO packages will always generate a library, due to the mechanics of linking
everything together.
  Any library (including CGO libraries) generated during compile will, when the
flag is specified, be '--install'ed into the corresponding subdirectory of the
path given to '--prefix' or to ${GOROOT}/pkg/${GOOS}_${GOARCH}/${PKG}.  See
section 2 for examples on using the '--install' options.

5. Incremental builds
  Each command executed by gofr is preceded by a check to see if the input
files are newer than the output file, if it exists.  If it is determined that
they are not, the command is skipped.  Thus, if modification times are stored
appropriately, gofr will incrementally build and link your project in an
intelligent way.  All commands will be listed in the verbose (-v) output, but
the ones which are skilled will be bash-style commented out.

6. Contact
  To contact me, send an email to Kyle Lemons <kyle> at <kylelemons.net> or give
me a shout on #go-nuts (nick: Eko).

7. Acknowledgements
  Creator: Kyle Lemons
    Ares (bitbucket.org/ares)

  Thanks a ton to Ares, who forked and fixed numerous issues in gofr when I did
not have the time to do so.