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 To think about
 111
 112 1. After several updates of the repository, we have many outdated
 113    Debian packages in the archive cache. I prefer removing them
 114    with a skriptlet like
 115
 116         cd /var/cache/apt/archives \
 117         && for i in $(ls | cut -f1 -d_ | uniq -c | egrep -v "^ *1 " | sed -e 's/^\s*[0-9]*\s//')
 118            do
 119                 ls -t ${i}_* | tail -n +2 | xargs -r rm
 120            done
 121
 122 2. To investigate which packages are already available in your repository
 123    and which ones are not, you may add your packages list to your /etc/apt/sources.list
 124    and perform
 125
 126         sudo apt-get update
 127         for i in `grep -i net all_pkgs `
 128         do
 129                 a=`echo $i|tr 'A-Z' 'a-z'`
 130                 echo "$i:$a"
 131                 apt-cache search r-cran-$a
 132         done
 133
 134 To debug:
 135
 136 $ cran2deb help
 137 will display a short summary of help for each cran2deb command.
 138
 139 The -d option will prevent the cleaning of the unpacked source code.
 140
 141
 142 Concerning data/:
 143 This contains scripts necessary to recreate the database should you lose the
 144 database. It's a backup that can be versioned by SVN. There is a script called
 145 pull that, when run from the data directory will recreate all the files from
 146 the database EXCEPT for the licenses. The licenses cannot be recreated because
 147 licenses can be based on one-way hashes.  This process could certainly be
 148 improved.
 149