trunk/inst/doc/README

   1 To install:
   2
   3 Please install a series of packages that you will need to
   4 run cran2deb successfully:
   5
   6         sudo apt-get install pbuilder python-gpgme gnupg-agent
   7
   8 You may install cran2deb manually
   9
  10         $ cd ..
  11         $ R CMD INSTALL cran2deb
  12
  13         copy cran2deb/exec/cran2deb into somewhere in your executable path (e.g.,
  14         /usr/local/bin, $home/bin)
  15
  16 or prepare a Debian package for it
  17
  18         fakeroot debian/rules binary
  19         sudo dpkg -i ../r-*cran2deb*.deb
  20
  21
  22 To configure:
  23
  24 1. You need a web server serving from say, /var/www/cran2deb/
  25
  26 Let ROOT be the value returned by running: cran2deb root
  27 Let SYS be the system you wish to build for (e.g., debian-amd64)
  28 Create user "c2d" who shall have write permissions to the archive.
  29
  30 2. create /etc/cran2deb
  31    a. copy ROOT/etc/* into /etc/cran2deb/
  32    b. ensure ROOT/etc/sys/SYS is set up
  33    c. /etc/cran2deb/archive should be a symlink pointing to /var/www/cran2deb/
  34
  35     $ ln -s /var/www/cran2deb/ /etc/cran2deb/archive
  36     $ mkdir /var/www/cran2deb/SYS
  37
  38    d. modify OTHERMIRROR of /etc/cran2deb/sys/SYS/pbuilderrc.in to point to your webserver.
  39       As long as the packages on debian.cran.r-project.org are not signed with a
  40       current key, just rebuild also the architecture-dependent packages or find
  41       a way for pbuilder to ignore the failing gpg signature check.
  42
  43       Example:
  44       OTHERMIRROR='deb http://master.dermacloud.uni-luebeck.de/cran2deb/rep testing main'
  45
  46       The above URL works for the reprepro tool. For mini-dinstall the URL
  47       may be slightly different. Please check after the first packages have been
  48       built that do not depend on other packages external to Debian.
  49
  50    e. run: cran2deb repopulate
  51
  52 3. cran2deb needs a persistent cache outside of R's control. therefore, create
  53     /var/cache/cran2deb, writable by whichever user(s) will run cran2deb.
  54
  55 4. add to /etc/rc.local:
  56         # one mini-dinstall daemon for each apt repo
  57         for sys in debian-i386 debian-amd64
  58         do
  59                 mini-dinstall -c /etc/cran2deb/sys/$sys/mini-dinstall.conf
  60         done
  61    and execute.
  62
  63 5. manual change - allow cran2deb user to execute pdebuild as root via sudo
  64         c2d      ALL=(ALL) SETENV: NOPASSWD: /usr/sbin/pdebuild
  65    The "SETENV:" is important.
  66
  67 6. run: cran2deb update
  68    This will also create the pbuilder environment if not already existing.
  69
  70 7. manual changes - create a gpg key for your packages
  71         gpg --genkey
  72    and read through 'man gpg-agent' to set it up. Add that key to the
  73    pbuilder environment so the packages you signed and uploaded are
  74    indeed acceptable to the distribution.
  75
  76         pbuilder --login \
  77                  --basetgz /var/cache/pbuilder/base-cran2deb-debian-amd64.tgz \
  78                  --save-after-login
  79
  80    Once logged in, in a separate shell perform as cran2deb user a
  81
  82         gpg --export -a
  83
  84    which should only be one (your) public key. Copy it with the mouse and
  85    add it to your pbuilder login shell via
  86
  87         apt-key add -
  88
  89    (return) to expect the key from stdin. Paste it, press CTRL-D to end
  90    the input. Another CTRL-D or 'exit' to leave the shell and have the
  91    base.tgz updated.
  92
  93    Also, you should allow the arch-independent R packages to be retrieved
  94    from the public cran2deb effort. This also requires that key to be
  95    available. From a local shell copy again that key
  96
  97         gpg --recv-key BFAEA5C2
  98         gpg --export -a BFAEA5C2
  99
 100    and use 'apt-key add -' as before.
 101
 102 8. Try building a simple package: cran2deb build zoo
 103    (The result will be in /var/cache/cran2deb/results/SYS)
 104
 105 9. Check the specification of your pbuilder settings and run
 106    'cran2deb update'. Do not run 'cran2deb update full' which
 107    creates a new pbuilder environment and will require the
 108    adding of keys again.
 109
 110 10. Educate yourself about the schema of the sqlite3 database,
 111    which is likely to reside at ~/cache/cran2deb.db
 112    and is directly accessible via calling from the
 113    UNIX command line 'sqlite3 ~/cache/cran2deb.db' .
 114
 115    The sqlite3 shell will directly attach to the database.
 116    See the tables first
 117
 118         sqlite> .tables
 119         blacklist_packages  debian_dependency   license_override
 120         builds              forced_depends      packages
 121         database_versions   license_hashes      sysreq_override
 122
 123    and then the schema of the one or other table of interest, e.g.
 124
 125    sqlite> .schema debian_dependency
 126         CREATE TABLE debian_dependency (
 127                 id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
 128                 alias TEXT NOT NULL,
 129                 build INTEGER NOT NULL,
 130                 debian_pkg TEXT NOT NULL ,
 131                 UNIQUE (alias,build,debian_pkg) );
 132    sqlite> .schema forced_depends
 133         CREATE TABLE forced_depends (
 134                 r_name TEXT NOT NULL,
 135                 depend_alias TEXT NOT NULL,
 136                 PRIMARY KEY (r_name,depend_alias) );
 137    sqlite> .schema blacklist_packages
 138         CREATE TABLE blacklist_packages (
 139                 package TEXT PRIMARY KEY NOT NULL,
 140                 nonfree INTEGER NOT NULL DEFAULT 0,
 141                 obsolete INTEGER NOT NULL DEFAULT 0,
 142                 broken_dependency INTEGER NOT NULL DEFAULT 0,
 143                 unsatisfied_dependency INTEGER NOT NULL DEFAULT 0,
 144                 breaks_cran2deb INTEGER NOT NULL DEFAULT 0,
 145                 other INTEGER NOT NULL DEFAULT 0,
 146                 explanation TEXT NOT NULL);
 147    sqlite> .schema builds
 148         CREATE TABLE builds (
 149                 id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
 150                 system TEXT NOT NULL ,package TEXT NOT NULL,
 151                 r_version TEXT NOT NULL ,deb_epoch INTEGER NOT NULL,
 152                 deb_revision INTEGER NOT NULL ,db_version INTEGER NOT NULL,
 153                 date_stamp TEXT NOT NULL ,time_stamp TEXT NOT NULL,
 154                 scm_revision TEXT NOT NULL ,success INTEGER NOT NULL,
 155                 log TEXT,
 156                 UNIQUE(package,system,r_version,deb_epoch,deb_revision,db_version));
 157    sqlite> .schema database_versions
 158         CREATE TABLE database_versions (
 159                 version INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
 160                 version_date INTEGER NOT NULL,
 161                 base_epoch INTEGER NOT NULL );
 162    sqlite> .schema license_hashes
 163         CREATE TABLE license_hashes (
 164                 name TEXT NOT NULL,
 165                 sha1 TEXT PRIMARY KEY NOT NULL );
 166    sqlite> .schema license_override
 167         CREATE TABLE license_override (
 168                 name TEXT PRIMARY KEY NOT NULL,
 169                 accept INT NOT NULL );
 170    sqlite> .schema packages
 171         CREATE TABLE packages (
 172                 package TEXT PRIMARY KEY NOT NULL,
 173                 latest_r_version TEXT );
 174    sqlite> .schema sysreq_override
 175         CREATE TABLE sysreq_override (
 176                 depend_alias TEXT NOT NULL,
 177                 r_pattern TEXT PRIMARY KEY NOT NULL );
 178
 179    The sqlite3 shell allows to modify all those entries. For a
 180    restart with defaults entries distributed via svn, run "cran2deb
 181    repopulate". To update the data stored in svn, change to the data
 182    directory and run "./pull". Caveat, prior to that, make sure the
 183    license data was read in by you. This is not performed automatically in
 184    repopulate, a bit to protect us and stress that everyone is reponsible
 185    for their own respective interpretation of a license's constraints
 186    and the effect on a redistribution of source and/or binary.
 187
 188 To think about
 189
 190 1. After several updates of the repository, we have many outdated
 191    Debian packages in the pbuilder's archive cache. I prefer removing
 192    them with a skriptlet like
 193
 194         cd /var/cache/apt/archives \
 195         && for i in $(ls | cut -f1 -d_ | uniq -c | egrep -v "^ *1 " | sed -e 's/^\s*[0-9]*\s//')
 196            do
 197                 ls -t ${i}_* | tail -n +2 | xargs -r rm
 198            done
 199
 200 2. To investigate which packages are already available in your repository
 201    and which ones are not, you may add your packages list to your /etc/apt/sources.list
 202    and perform
 203
 204         sudo apt-get update
 205         for i in `grep -i net all_pkgs `
 206         do
 207                 a=`echo $i|tr 'A-Z' 'a-z'`
 208                 echo "$i:$a"
 209                 apt-cache search r-cran-$a
 210         done
 211
 212 To debug:
 213
 214 $ cran2deb help
 215 will display a short summary of help for each cran2deb command.
 216
 217 The -d option will prevent the cleaning of the unpacked source code.
 218
 219 To improve:
 220
 221  * The runtime dependencies for Rgraphviz are outdated (there is no libraphviz4
 222    any more). To get the package run  this was not changed to "alias_run
 223    libgraphviz libgraphviz-dev" but this can certainly be optimised
 224    towards something less resource-hungry.
 225
 226
 227 Concerning data/:
 228 This contains scripts necessary to recreate the database should you lose the
 229 database. It's a backup that can be versioned by SVN. There is a script called
 230 pull that, when run from the data directory will recreate all the files from
 231 the database EXCEPT for the licenses. The licenses cannot be recreated because
 232 licenses can be based on one-way hashes.  This process could certainly be
 233 improved.
 234