Manpage update, INSTALL instructions update

INSTALL

@@ -1,13 +1,13 @@
-Note: rock will install a launching script to /usr/bin/ by default,
-and its manpage to /usr/man/man1 (on *nix platforms)
 
-You can change the prefix by running PREFIX=/usr/local/ sudo make install
-for example, or even install it by hand (it's not that hard)
+Note: make install does two things
+  1) Copy the manpage to /usr/local/man/man1 (override with MAN_INSTALL_PATH)
+  2) Create a symbolic link from bin/rock to /usr/bin/rock
+     (override with PREFIX=/usr/local or BIN_INSTALL_PATH=~/bin)
 
 You have a -source release
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-'make bootstrap && sudo make install'
+'make && sudo make install'
 
 You have a binary release (e.g. rock-X.X.X-linux32, rock-X.X.X-win32, etc.)
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -40,4 +40,6 @@ If we don't have your platform/arch, try to install the Boehm GC yourself,
 and compile with -gc=dynamic (it'll link with -lgc instead of the static
 binary builds)
 
-http://www.hpl.hp.com/personal/Hans_Boehm/gc/
+http://www.hpl.hp.com/personal/Hans_Boehm/gc/
+
+Don't be afraid to open Makefile and build/Makefile

Makefile

@@ -1,10 +1,14 @@
-.PHONY:all clean mrproper test-ast
+.PHONY: all clean mrproper prepare_bootstrap bootstrap
 PARSER_GEN=greg
 NQ_PATH=source/rock/frontend/NagaQueen.c
 DATE=$(shell date +%Y-%m-%d)
 TIME=$(shell date +%H:%M)
 OOC_OWN_FLAGS=-sourcepath=source -driver=sequence -noclean -g -v -shout +-w
 
+PREFIX?=/usr
+MAN_INSTALL_PATH?=/usr/local/man/man1
+BIN_INSTALL_PATH?=${PREFIX}/bin
+
 ifdef WINDIR
 	OOC_OWN_FLAGS+=+-DROCK_BUILD_DATE=\\\"${DATE}\\\" +-DROCK_BUILD_TIME=\\\"${TIME}\\\"
 else
@@ -14,11 +18,7 @@ endif
 OOC?=rock
 OOC_CMD=${OOC} ${OOC_OWN_FLAGS} ${OOC_FLAGS}
 
-all:
-	make clean noclean
-
-noclean:
-	${OOC_CMD} rock/rock -o=bin/rock ${NQ_PATH}
+all: bootstrap
 
 # Regenerate NagaQueen.c from the greg grammar
 # you need ../nagaqueen and greg to be in your path
@@ -47,6 +47,26 @@ bootstrap:
 	@echo "Now re-compiling ourself"
 	OOC=bin/c_rock ROCK_DIST=. make all
 	@echo "Congrats! you have a boostrapped version of rock in bin/rock now. Have fun!"
+
+# Copy the manpage and create a symlink to the binary
+install:
+	cp -f docs/rock.1 ${MAN_INSTALL_PATH}/
+	ln -s $(shell pwd)/bin/rock* ${BIN_INSTALL_PATH}/
+
+# Regenerate the man page from docs/rock.1.txt You need ascidoc for that
+man:
+	cd docs/ && a2x -f manpage rock.1.txt
+
+# Compile a clean rock with itself
+self:
+	make clean noclean
+
+# For rock developers - recompile without cleaning, for small changes
+# that don't trigger the fragile base class problem.
+#  - http://en.wikipedia.org/wiki/Fragile_base_class
+# This should be fixed by caching the class hierarchy with the json backend
+noclean:
+	${OOC_CMD} rock/rock -o=bin/rock ${NQ_PATH}
 
 clean:
 	rm -rf *_tmp/

docs/rock.1

@@ -0,0 +1,212 @@
+'\" t
+.\"     Title: rock
+.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\"      Date: 04/22/2010
+.\"    Manual: \ \&
+.\"    Source: \ \&
+.\"  Language: English
+.\"
+.TH "ROCK" "1" "04/22/2010" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+rock \- rapid ooc compiler without kludges
+.SH "SYNOPSIS"
+.sp
+\fBrock\fR [\fIOPTIONS\fR] \fIFILES\fR
+.SH "DESCRIPTION"
+.sp
+By default, rock takes the input files and compiles each, producing executables\&. However, this behaviour can be adjusted via command line options\&.
+.SH "OPTIONS"
+.PP
+\fB\-v, \-verbose\fR
+.RS 4
+Print more information during the build process, useful for debugging\&.
+.RE
+.PP
+\fB\-vv, \-veryVerbose\fR
+.RS 4
+Print even more information!
+\fB\-vv\fR
+implies
+\fB\-v\fR\&.
+.RE
+.PP
+\fB\-g, \-debug\fR
+.RS 4
+Compile with debug information\&.
+.RE
+.PP
+\fB\-noclean\fR
+.RS 4
+Don\(cqt delete any temporary file produced by the backend, useful for debugging\&.
+.RE
+.PP
+\fB\-backend=[c]\fR
+.RS 4
+Choose the rock backend\&. Currently, only the default backend
+\fIc\fR
+is supported\&.
+.RE
+.PP
+\fB\-gcc,\-tcc,\-icc,\-clang,\-onlygen\fR
+.RS 4
+Choose the compiler backend\&. (default=gcc) Available compilers are the GNU Compiler Collection, TinyCC, Intel C++ Compiler and the LLVM\(cqs clang frontend\&. Also, you can pass
+\fIonlygen\fR
+to only generate the code and not to run any compiler\&.
+.RE
+.PP
+\fB\-gc=[dynamic,static,off]\fR
+.RS 4
+Link dynamically, link statically, or don\(cqt link with the boehm GC at all\&. Linking dynamically is \-lgc, linking statically uses libs/\fIARCH\fR/libgc\&.a where
+\fIARCH\fR
+is one of linux32, linux64, win32, osx, etc\&. \-gc=off replace all calls of gc_malloc() with malloc(), and similarly with calloc, realloc, free\&. For more infos, see
+http://docs\&.ooc\-lang\&.org/
+.RE
+.PP
+\fB\-driver=[combine,sequence,make]\fR
+.RS 4
+Choose the compile driver to use\&.
+\fIcombine\fR
+compiles all C files combined,
+\fIsequence\fR
+compiles them sequentially,
+\fImake\fR
+creates a build/ directory with all the \&.c files and a Makefile\&.
+.RE
+.PP
+\fB\-sourcepath=PATH\fR
+.RS 4
+Specify a colon\-separated (for *nix) or semicolon\-separated path list in which rock should look for your source files\&. (default=current directory)
+.RE
+.PP
+\fB\-outpath=PATH\fR
+.RS 4
+Place all \&.c and \&.h files in
+\fIPATH\fR\&. (default=\fIrock_tmp/\fR)
+.RE
+.PP
+\fB\-IPATH, \-incpath=PATH\fR
+.RS 4
+Add
+\fIPATH\fR
+to the C header search path\&.
+.RE
+.PP
+\fB\-LPATH, \-libpath=PATH\fR
+.RS 4
+Add
+\fIPATH\fR
+to the C library search path\&.
+.RE
+.PP
+\fB\-lLIB\fR
+.RS 4
+Link dynamically with library
+\fILIB\fR\&.
+.RE
+.PP
+\fB\-t, \-timing\fR
+.RS 4
+Print how much time the compilation took\&.
+.RE
+.PP
+\fB\-r, \-run\fR
+.RS 4
+Run the exectuable after a successful compilation\&.
+.RE
+.PP
+\fB\-editor=EDITOR\fR
+.RS 4
+The editor to run when an error in a ooc file was encountered\&.
+.RE
+.PP
+\fB\-entrypoint=FUNC\fR
+.RS 4
+Use FUNC as entrypoint\&. (default=\fImain\fR)
+.RE
+.PP
+\fB\-c\fR
+.RS 4
+Compile, but skip the linking step\&. Useful if you want to use your ooc code from a program written in another language\&.
+.RE
+.PP
+\fB\-linker=LINKER\fR
+.RS 4
+Use
+\fILINKER\fR
+in the last step of the sequence driver\&.
+.RE
+.PP
+\fB\-nomain\fR
+.RS 4
+Don\(cqt write a default main function\&.
+.RE
+.PP
+\fB\-nolines\fR
+.RS 4
+Print no #line directives in the C files\&.
+.RE
+.PP
+\fB\-shout\fR
+.RS 4
+Print a big fat status indicator (usually
+\fI[ OK ]\fR) when a build process is finished\&.
+.RE
+.PP
+\fB\-blowup=ROUNDS\fR
+.RS 4
+Debugging option: Terminate rock after
+\fIROUNDS\fR
+tinkerer rounds\&. (default=32)
+.RE
+.PP
+\fB\-V, \-version, \-\-version\fR
+.RS 4
+Print rock\(cqs version and exit\&.
+.RE
+.PP
+\fB\-h, \-help, \-\-help\fR
+.RS 4
+Print this help and exit\&.
+.RE
+.PP
+\fB\-mARCH\fR
+.RS 4
+Specify the architecture (either 32 or 64)\&.
+.RE
+.PP
+\fB+\&...\fR
+.RS 4
+Pass extra arguments to the compiler\&. Example:
+\fI+\-Wall\fR
+will pass
+\fI\-Wall\fR
+to gcc\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+\fB0\fR
+.RS 4
+Success\&.
+.RE
+.PP
+\fB1\fR
+.RS 4
+Failure\&.
+.RE
+.SH "RESOURCES"
+.sp
+Website: http://ooc\-lang\&.org
+.SH "COPYING"
+.sp
+rock is (c) 2009\-2010 by Amos Wenger & the ooc crew, licensed under a two\-clause BSD license\&. See \fILICENSE\fR for details\&.

docs/rock.1.txt

@@ -41,13 +41,19 @@ OPTIONS
 
 *-gc=[dynamic,static,off]*::
     Link dynamically, link statically, or don't link with the boehm GC at all.
+    Linking dynamically is -lgc, linking statically uses libs/'ARCH'/libgc.a
+    where 'ARCH' is one of linux32, linux64, win32, osx, etc.
+    -gc=off replace all calls of gc_malloc() with malloc(), and similarly
+    with calloc, realloc, free. For more infos, see http://docs.ooc-lang.org/
 
 *-driver=[combine,sequence,make]*::
     Choose the compile driver to use. 'combine' compiles all C files combined, 
-    'sequence' compiles them sequentially, 'make' creates a Makefile.
+    'sequence' compiles them sequentially, 'make' creates a build/ directory
+    with all the .c files and a Makefile.
 
 *-sourcepath=PATH*::
-    Pass the location of your source files. (default=current directory)
+    Specify a colon-separated (for *nix) or semicolon-separated path list
+    in which rock should look for your source files. (default=current directory)
 
 *-outpath=PATH*::
     Place all .c and .h files in 'PATH'. (default='rock_tmp/')
@@ -59,7 +65,7 @@ OPTIONS
     Add 'PATH' to the C library search path.
 
 *-lLIB*::
-    Link with library 'LIB'.
+    Link dynamically with library 'LIB'.
 
 *-t, -timing*::
     Print how much time the compilation took.
@@ -74,7 +80,8 @@ OPTIONS
     Use FUNC as entrypoint. (default='main')
 
 *-c*::
-    Don't link.
+    Compile, but skip the linking step. Useful if you want to
+    use your ooc code from a program written in another language.
 
 *-linker=LINKER*::
     Use 'LINKER' in the last step of the sequence driver.
@@ -83,13 +90,13 @@ OPTIONS
     Don't write a default main function.
 
 *-nolines*::
-    Print no lines directives to the C files.
+    Print no #line directives in the C files.
 
 *-shout*::
     Print a big fat status indicator (usually '[ OK ]') when a build process is finished.
 
 *-blowup=ROUNDS*::
-    Terminate rock after ROUNDS tinkerer rounds. (default=32)
+    Debugging option: Terminate rock after 'ROUNDS' tinkerer rounds. (default=32)
 
 *-V, -version, --version*::
     Print rock's version and exit.