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
  72         gpg --genkey
  73
  74    and read through 'man gpg-agent' to set it up. Add that key to the
  75    pbuilder environment so the packages you signed and uploaded are
  76    indeed acceptable to the distribution.
  77
  78         sudo pbuilder  --login --save-after-login \
  79              --basetgz /var/cache/pbuilder/base-cran2deb-debian-amd64.tgz
  80
  81    Once logged in, in a separate shell perform as cran2deb user a
  82
  83         gpg --export -a
  84
  85    which should only be one (your) public key. Copy it with the mouse and
  86    add it to your pbuilder login shell via
  87
  88         apt-key add -
  89
  90    (return) to expect the key from stdin. Paste it, press CTRL-D to end
  91    the input. Another CTRL-D or 'exit' to leave the shell and have the
  92    base.tgz updated.
  93
  94    Also, you should allow the arch-independent R packages to be retrieved
  95    from the public cran2deb effort. This also requires that key to be
  96    available. From a local shell copy again that key
  97
  98         gpg --recv-key BFAEA5C2
  99         gpg --export -a BFAEA5C2
 100
 101    and use 'apt-key add -' as before.
 102
 103 8. Try building a simple package: cran2deb build zoo
 104    (The result will be in /var/cache/cran2deb/results/SYS)
 105
 106 9. Check the specification of your pbuilder settings and run
 107    'cran2deb update'. Do not run 'cran2deb update full' which
 108    creates a new pbuilder environment and will require the
 109    adding of keys again.
 110
 111 10. Educate yourself about the schema of the sqlite3 database,
 112    which is likely to reside at ~/cache/cran2deb.db
 113    and is directly accessible via calling from the
 114    UNIX command line 'sqlite3 ~/cache/cran2deb.db' .
 115
 116    The sqlite3 shell will directly attach to the database.
 117    See the tables first
 118
 119         sqlite> .tables
 120         blacklist_packages  debian_dependency   license_override
 121         builds              forced_depends      packages
 122         database_versions   license_hashes      sysreq_override
 123
 124    and then the schema of the one or other table of interest, e.g.
 125
 126    sqlite> .schema debian_dependency
 127         CREATE TABLE debian_dependency (
 128                 id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
 129                 alias TEXT NOT NULL,
 130                 build INTEGER NOT NULL,
 131                 debian_pkg TEXT NOT NULL ,
 132                 UNIQUE (alias,build,debian_pkg) );
 133    sqlite> .schema forced_depends
 134         CREATE TABLE forced_depends (
 135                 r_name TEXT NOT NULL,
 136                 depend_alias TEXT NOT NULL,
 137                 PRIMARY KEY (r_name,depend_alias) );
 138    sqlite> .schema blacklist_packages
 139         CREATE TABLE blacklist_packages (
 140                 package TEXT PRIMARY KEY NOT NULL,
 141                 nonfree INTEGER NOT NULL DEFAULT 0,
 142                 obsolete INTEGER NOT NULL DEFAULT 0,
 143                 broken_dependency INTEGER NOT NULL DEFAULT 0,
 144                 unsatisfied_dependency INTEGER NOT NULL DEFAULT 0,
 145                 breaks_cran2deb INTEGER NOT NULL DEFAULT 0,
 146                 other INTEGER NOT NULL DEFAULT 0,
 147                 explanation TEXT NOT NULL);
 148    sqlite> .schema builds
 149         CREATE TABLE builds (
 150                 id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
 151                 system TEXT NOT NULL ,package TEXT NOT NULL,
 152                 r_version TEXT NOT NULL ,deb_epoch INTEGER NOT NULL,
 153                 deb_revision INTEGER NOT NULL ,db_version INTEGER NOT NULL,
 154                 date_stamp TEXT NOT NULL ,time_stamp TEXT NOT NULL,
 155                 scm_revision TEXT NOT NULL ,success INTEGER NOT NULL,
 156                 log TEXT,
 157                 UNIQUE(package,system,r_version,deb_epoch,deb_revision,db_version));
 158    sqlite> .schema database_versions
 159         CREATE TABLE database_versions (
 160                 version INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
 161                 version_date INTEGER NOT NULL,
 162                 base_epoch INTEGER NOT NULL );
 163    sqlite> .schema license_hashes
 164         CREATE TABLE license_hashes (
 165                 name TEXT NOT NULL,
 166                 sha1 TEXT PRIMARY KEY NOT NULL );
 167    sqlite> .schema license_override
 168         CREATE TABLE license_override (
 169                 name TEXT PRIMARY KEY NOT NULL,
 170                 accept INT NOT NULL );
 171    sqlite> .schema packages
 172         CREATE TABLE packages (
 173                 package TEXT PRIMARY KEY NOT NULL,
 174                 latest_r_version TEXT );
 175    sqlite> .schema sysreq_override
 176         CREATE TABLE sysreq_override (
 177                 depend_alias TEXT NOT NULL,
 178                 r_pattern TEXT PRIMARY KEY NOT NULL );
 179
 180    The sqlite3 shell allows to modify all those entries. For a
 181    restart with defaults entries distributed via svn, run "cran2deb
 182    repopulate". To update the data stored in svn, change to the data
 183    directory and run "./pull". Caveat, prior to that, make sure the
 184    license data was read in by you. This is not performed automatically in
 185    repopulate, a bit to protect us and stress that everyone is reponsible
 186    for their own respective interpretation of a license's constraints
 187    and the effect on a redistribution of source and/or binary.
 188
 189 11.Add licenses the way you think it is right. The script in
 190    'exec/repopulate' may offer ideas on how to mass-include what
 191    you find in the svn. For new entries, you may prefer using
 192    'cran2deb' license that expects to learn from from the command
 193    line how to treat individual licenses:
 194
 195       $ cran2deb license accept akima
 196       I: cran2deb svn: 344 building for debian-amd64 at 2011-02-11 18:46:21
 197       N: adding akima accept? TRUE
 198
 199       $ cran2deb license hash_sha1 akima 485316717b03afbd6d20f7810f9123b4445c8660
 200       I: cran2deb svn: 344 building for debian-amd64 at 2011-02-11 18:46:37
 201       N: adding hash 485316717b03afbd6d20f7810f9123b4445c8660 for akima
 202
 203       $ cran2deb license ls
 204       I: cran2deb svn: 344 building for debian-amd64 at 2011-02-11 18:46:53
 205       accept akima
 206       hash_sha1 akima 485316717b03afbd6d20f7810f9123b4445c8660
 207
 208    What happens here is that a license file was read and if that is
 209    having the same hash value, then it is mapped to the license 'akima'.
 210    The license 'akima' then again is told to be acceptable. It happened
 211    here that the license is of the same name as the package that it
 212    occurs in.
 213
 214 To think about
 215
 216 1. After several updates of the repository, we have many outdated
 217    Debian packages in the pbuilder's archive cache. I prefer removing
 218    them with a skriptlet like
 219
 220         cd /var/cache/apt/archives \
 221         && for i in $(ls | cut -f1 -d_ | uniq -c | egrep -v "^ *1 " | sed -e 's/^\s*[0-9]*\s//')
 222            do
 223                 ls -t ${i}_* | tail -n +2 | xargs -r rm
 224            done
 225
 226 2. To investigate which packages are already available in your repository
 227    and which ones are not, you may add your packages list to your /etc/apt/sources.list
 228    and perform
 229
 230         sudo apt-get update
 231         for i in `grep -i net all_pkgs `
 232         do
 233                 a=`echo $i|tr 'A-Z' 'a-z'`
 234                 echo "$i:$a"
 235                 apt-cache search r-cran-$a
 236         done
 237
 238 3. If running on a separate partition, the place reserved for cran2deb is not unlikely
 239    to exceed your expectation, especially when also running BioConductor. You may
 240    consider running cran2deb on logical volumes, like by LVM. Together with a file
 241    system that allows its extension, the process is rather straight forward:
 242
 243         # lvextend -L+40G /dev/vg0/cran2deb
 244         Extending logical volume cran2deb to 115.04 GiB
 245         Logical volume cran2deb successfully resized
 246         # xfs_growfs /dev/vg0/cran2deb
 247         meta-data=/dev/dm-6              isize=256    agcount=21, agsize=983040 blks
 248                  =                       sectsz=512   attr=2
 249         data     =                       bsize=4096   blocks=19671040, imaxpct=25
 250                  =                       sunit=0      swidth=0 blks
 251         naming   =version 2              bsize=4096   ascii-ci=0
 252         log      =internal               bsize=4096   blocks=2560, version=2
 253                  =                       sectsz=512   sunit=0 blks, lazy-count=1
 254         realtime =none                   extsz=4096   blocks=0, rtextents=0
 255         data blocks changed from 19671040 to 30156800
 256
 257    The directory does not even need to unmounted for that with XFS.
 258
 259
 260 To debug:
 261
 262 $ cran2deb help
 263 will display a short summary of help for each cran2deb command.
 264
 265 The -d option will prevent the cleaning of the unpacked source code.
 266
 267 To improve:
 268
 269  * The runtime dependencies for Rgraphviz are outdated (there is no libraphviz4
 270    any more). To get the package run  this was not changed to "alias_run
 271    libgraphviz libgraphviz-dev" but this can certainly be optimised
 272    towards something less resource-hungry.
 273
 274
 275 Concerning data/:
 276 This contains scripts necessary to recreate the database should you lose the
 277 database. It's a backup that can be versioned by SVN. There is a script called
 278 pull that, when run from the data directory will recreate all the files from
 279 the database EXCEPT for the licenses. The licenses cannot be recreated because
 280 licenses can be based on one-way hashes.  This process could certainly be
 281 improved. But one gets the hang of it ater a while. So don't despair.
 282