summaryrefslogtreecommitdiff
path: root/HACKING
diff options
context:
space:
mode:
Diffstat (limited to 'HACKING')
-rw-r--r--HACKING99
1 files changed, 97 insertions, 2 deletions
diff --git a/HACKING b/HACKING
index 062814a..eb7b34f 100644
--- a/HACKING
+++ b/HACKING
@@ -5,6 +5,12 @@
in commit 2 before commit 1
//////////////////////////////////////////////////////////////////////
+ I know this file is long* and boring. I try to keep it preened and
+ informative, but would rather spend my time actually hacking. If
+ you think you can help this file, have at it! ~ Luke Shumaker
+
+ * at 200+ lines, it's longer than any rvs source file
+
hacking
There are two main parts to rvs, the wrapper, and the core. The
@@ -13,6 +19,7 @@
executables that do all the real work.
build system
+ (be sure to read the `configuration' section of `README' first)
The build system rvs uses is rather simple.
`./configure' does two things:
@@ -78,7 +85,7 @@
As you probably noticed (if you've looked at the blueprints or
source files), only directories and regular files have been
- implemented as of rvs 0.6.1.
+ implemented as of rvs 0.6.2.
After `rvs commit' has done this, it creates a meta-file for that
commit. The meta file contains author, copyright owner, licence
@@ -92,7 +99,8 @@
functions in the propper locations.
Any commit function should take a filename as an argument and
- output the according commit id to stdout.
+ output the according commit id to stdout. stderr should be used
+ for all messages.
Any get function should take the commit id as an argument and
uses stdout only if verbose, or to report errors.
@@ -106,6 +114,93 @@
3. one can use any language to write new modules, without
having to worry about bindings
+ $$libdir$$/lib/
+
+ I have created two 'libraries' for use by rvs components. They
+ provide several functions that can be accessed by shell script by
+ using the code:
+ source "`rvs -d`/lib/stdio"
+ or
+ source "`rvs -d`/lib/rvsdb"
+ (`rvs -d' returns $$libdir$$)
+ stdio provides several functions for printing messages:
+ verbose MESSAGE
+ print MESSAGE to stdout only if $verbose is set to '-v'
+ out MESSAGE
+ print MESSAGE to stdout if $verbose isn't set to '-q'
+ warn MESSAGE
+ print "rvs: MESSAGE" to stderr
+ error MESSAGE
+ print "rvs: MESSAGE" and a quick message about `rvs --help'
+ (hinting at user error) to stderr, then exit with error
+ fatal MESSAGE
+ For internal error. Print "rvs: MESSAGE" to stderr and exit
+ with error
+ version
+ print the version information and exit with success
+
+ rvsdb provides several functions and variables for dealing with the
+ rvs database:
+ $repo
+ the directory of the database (./.rvs)
+ getid FILE
+ returns what the id of a given file would be if it were in
+ the database. This is used to know where to put files when
+ commiting them. In 0.6.[0-2] this is just the sha1sum of
+ the file
+ NOTE: the "log*" functions aren't very stable or developed
+ loginit FILE
+ initialize an rvs log at FILE. These logs are used for
+ metafiles, directory listings, and (probably) eventually
+ checkout logs
+ lograw LOG
+ prepare LOG for reading, and write the output to stdout (to
+ pipe into another function). This is mostly for internal
+ use by rvsdb
+ logread LOG VAR
+ read variable VAR from the logfile LOG
+ logwrite LOG VAR VAL
+ set variable VAR to VAL in the logfile LOG
+ logfind LOG VAL
+ return all the names of variables in logfile LOG who have
+ the value VAL
+
+ the database (.rvs/*)
+
+ So, what are all these files doing in in the database? The scheme
+ is fairly simple. In the `.rvs' directory there are 2 directories,
+ the `files' directory, and the `tmp' directory. `tmp' is what it
+ sounds like, a place for rvs compnents to keep temporary files.
+ The wrapper sets TMPDIR, so you can create a unique file in there
+ with:
+ FILENAME=`tempfile`
+ The `files' directory is where all the data is kept.
+
+ When any file is commited, whether it be a regular file, a
+ directory, a link, or any other type of file, 2 file are created in
+ `.rvs/files', the "raw-file" and the "meta-file". When we speek of
+ file IDs, we mean the filename of the corresponding file in
+ `.rvs/files' in rvs 0.5.8-0.6.2 this is just the sha1sum of the
+ file. The meta-file stores everything not part of the file itself;
+ the filename, file-type, author, copyright owner, file permissions,
+ timestamps, etc, and the ID of the corresponding raw-file. In the
+ case of an regular file, the raw-file contains the file itself. For
+ directories, it contains pointers to each file inside the
+ directory.
+
+ $$libdir$$/commit calls $$libdir$$/commit.FILETYPE to generate the
+ raw-file, but generates the meta-file itself (in `.rvs/tmp', then
+ calls commit.f to commit the meta-file). It then returns the ID
+ of the meta-file. Therefore, the user never deals with the IDs of
+ raw-files, and doesn't need to. The metafiles contain pointers to
+ the corresponding raw-files.
+
+ To keep things modular, commit.f is the ONLY thing that should
+ actually put files in `.rvs/files', and get.f the only thing that
+ should get them. Everything else should call them.
+
+ final thoughts
+
I have set up bazaar repository at Launchpad:
https://launchpad.net/rvs
Only until rvs becomes self-hosting.