doc: document installation and some of the database internals

git-svn-id: svn://svn.r-forge.r-project.org/svnroot/cran2deb@129 edb9625f-4e0d-4859-8d74-9fd3b1da38cb

diff --git a/pkg/trunk/inst/doc/DB_NOTES b/pkg/trunk/inst/doc/DB_NOTES
new file mode 100644 (file)
index 0000000..0960026
--- /dev/null
+++ b/pkg/trunk/inst/doc/DB_NOTES
@@ -0,0 +1,81 @@
+this file documents some of R/db.R -- the DB interface code.
+
+
+table: sysreq_override
+fields: depend_alias TEXT, r_pattern TEXT
+
+SystemRequirements LIKE r_pattern are mapped onto the dependency alias
+depend_alias (this is a foreign key in debian_dependency).
+
+table: debian_dependency
+fields: id INTEGER PRIMARY KEY AUTOINCREMENT,
+        alias TEXT,
+        build INTEGER NOT NULL,
+        debian_pkg TEXT NOT NULL,
+        UNIQUE (alias,build,debian_pkg)
+
+sets up a dependency alias. each row is a Debian dependency entry, debian_pkg, which
+may be added to Depends: (and Build-Depends: if build = 1).
+
+table: forced_depends
+fields: r_name TEXT.
+        depend_alias TEXT,
+        PRIMARY KEY (r_name,depend_alias)'
+
+forces the R package r_name to have the dependencies implied by depend_alias (a foriegn
+key in debian_dependency).
+
+table: license_override
+fields: name TEXT PRIMARY KEY,
+        accept INT NOT NULL
+
+specifies whether the license, name, is accepted or rejected.
+
+table: license_hashes
+fields: name TEXT
+        sha1 TEXT PRIMARY KEY
+
+matches an SHA1 hash of the LICEN[CS]E file or part of the License: field to
+a particular license name (a foreign key in license_override).
+
+table: database_versions
+fields: version INTEGER PRIMARY KEY AUTOINCREMENT,
+        version_date INTEGER,
+        base_epoch INTEGER
+
+a version of the database. each time one of the above tables (but not the below
+tables) is updated, a new record is added to this table, indicating significant
+changes to the database. version_date indicates when this change occurred
+(seconds since UNIX epoch) and base_epoch is the Debian version epoch.
+
+in future, all of the above fields should be versioned and somehow linked to
+the packages that used them, so we only rebuild what is necessary.
+
+table: packages
+fields: package TEXT PRIMARY KEY,
+        latest_r_version TEXT
+
+a package, and its latest R version. this is a copy of the 'available'
+structure in the cran2deb R cache, and it is here as it allows queries on the
+'builds' table to be much simpler (and perhaps faster).
+
+table: builds
+fields: id INTEGER PRIMARY KEY AUTOINCREMENT,
+        package TEXT,
+        r_version TEXT,
+        deb_epoch INTEGER,
+        deb_revision INTEGER,
+        db_version INTEGER,
+        date_stamp TEXT,
+        git_revision TEXT,
+        success INTEGER,
+        log TEXT,
+        UNIQUE(package,r_version,deb_epoch,deb_revision,db_version)
+
+Each time a 'package' is built, its 'success' is logged, along with the
+particular database, cran2deb, R and Debian version information (db_version,
+git_revision, r_version, deb_epoch, deb_revision) and the current date
+(date_stamp). 'log' contains the output of the build process.
+
+A new 'deb_revision' is assigned to each successful build.
+

diff --git a/pkg/trunk/inst/doc/INSTALL_NOTES b/pkg/trunk/inst/doc/INSTALL_NOTES
new file mode 100644 (file)
index 0000000..4d47890
--- /dev/null
+++ b/pkg/trunk/inst/doc/INSTALL_NOTES
@@ -0,0 +1,56 @@
+git clone git://github.com/blundellc/cran2deb.git
+
+apt-get system requirements from DESCRIPTION
+apt-get install cdbs
+
+# install a web server
+apt-get install thttpd
+
+# add a group for cran2deb people
+addgroup cran2deb
+usermod -a -G cran2deb cb
+usermod -a -G cran2deb edd
+
+# set up web space
+mkdir /var/www/cran2deb
+chgrp cran2deb /var/www/cran2deb
+chmod 3775 /var/www/cran2deb
+
+# install prereq R packages
+r -e "install.packages(c('ctv','RSQLite','DBI','digest'))"
+R CMD INSTALL cran2deb
+
+# set up cran2deb space, as per README
+cp /usr/local/lib/R/site-library/cran2deb/exec/cran2deb  /usr/local/bin
+root=$(cran2deb root)
+mkdir /etc/cran2deb
+chgrp cran2deb /etc/cran2deb
+chmod 3775 /etc/cran2deb
+copy ROOT/etc/* to /etc/cran2deb
+ln -s /var/www/cran2deb/ /etc/cran2deb/archive
+edit /etc/cran2deb/pbuilder.in:
+OTHERMIRROR='deb http://localhost/users/cb/cran2deb/ unstable/$(ARCH)/ | deb http://localhost/users/cb/cran2deb/ unstable/all/'
+MIRRORSITE='http://ftp.debian.org/debian/'
+to
+OTHERMIRROR='deb http://localhost/cran2deb/ unstable/$(ARCH)/ | deb http://localhost/cran2deb/ unstable/all/'
+MIRRORSITE='http://ftp.at.debian.org/debian/'
+
+# fix permissions for group usage.
+mkdir /var/cache/cran2deb
+chgrp cran2deb /var/cache/cran2deb
+chmod 3775 /var/cache/cran2deb
+chgrp -R cran2deb $root
+chmod 3775 $root
+chmod -R g+w $root
+
+(log out then log in to get gid cran2deb)
+
+# build pbuilder archive, initialise database
+cran2deb update
+
+# check it works
+cran2deb build zoo
+
+# is handy
+apt-get install sqlite3
+