README

   1 POPCORN - Popularity Contest (for RPM)
   2 --------------------------------------
   3
   4 http://repo.or.cz/w/popcorn.git
   5
   6 Licensed under MIT License
   7 Copyright (c) 2009 Pavol Rusnak <stick@gk2.sk>
   8
   9 Introduction
  10 ------------
  11
  12 Popcorn lists system packages and for each package it reads access time of its
  13 "watched" files (see section Watched Files below). The most recent fileaccess
  14 time is considered as the "package access time". The packages are then split into
  15 four categories depending on the package install time and package access time:
  16
  17 * (r) recent
  18   - package has been recently installed (less than 30 days)
  19   - ( now - install_time < 30 days )
  20 * (v) voted
  21   - package is older than 30 days and has been used in the last 30 days
  22   - ( now - install_time > 30 days ) and ( now - access_time < 30 days)
  23 * (o) old
  24   - package is older than 30 days and hasn't been used recently
  25   - ( now - install_time > 30 days ) and ( now - access_time > 30 days)
  26 * (n) no-files
  27   - there are no watched files present in the package
  28   - access_time = 0
  29
  30 Each package falls exactly into one category, so (n + r + v + o) is the total
  31 number of the installed packages.
  32
  33 Popcorn is inspired by Debian Popcon available from http://popcon.debian.org/
  34
  35 Watched Files
  36 -------------
  37
  38 To find out whether the package has been used recently, access times of the files
  39 in the following directories are watched:
  40
  41 /bin
  42 /boot
  43 /lib
  44 /lib64
  45 /opt/gnome/bin
  46 /opt/gnome/sbin
  47 /opt/kde3/bin
  48 /opt/kde3/sbin
  49 /sbin
  50 /usr/bin
  51 /usr/games
  52 /usr/include
  53 /usr/lib
  54 /usr/lib64
  55 /usr/libexec
  56 /usr/sbin
  57
  58 Note: The files mounted from the noatime/relatime filesystems are not taken into
  59       consideration, because they would skew the results. If package contains
  60       only such files, it appears in 'no-files' category.
  61
  62 Files
  63 -----
  64
  65 popcorn-client
  66   * client-side written in Python
  67   * gathers info about packages and sends to server (either via e-mail or HTTP POST)
  68   * is called from cron every week (random time for each machine)
  69
  70 popcorn-server
  71   * server-side written in C and using libtdb library (http://tdb.samba.org)
  72   * reads info from stdin and saves it to stats.tdb
  73
  74 popcorn-rotate
  75   * called every week on server
  76   * move stats.tdb to stats-{year}-{week}.tdb and recreates stats.tdb
  77
  78 popcorn-dump
  79   * dumps stats.tdb to stdout
  80
  81 Submission format
  82 -----------------
  83
  84 Format is simple plaintext. First line contains string POPCORN followed by the
  85 popcorn version and architecture. Then the list of packages follows. Each package
  86 is prepended with one character describing the category (see Introduction) and
  87 the space. Plaintext size is around 30 KiB on casual machine, which could be
  88 later compressed to 10-15 KiB using HTTP gzip compression.
  89
  90 Format:
  91
  92 POPCORN <popcorn-client_version> <arch>
  93 <category> <package>
  94 ...
  95 <EOF>
  96
  97 Example:
  98
  99 POPCORN 0.1 x86_64
 100 o twolame
 101 r sxtopdf
 102 v mozilla-nspr
 103 v libsensors4
 104 n snmp-mibs
 105 n branding-openSUSE
 106 v utempter
 107 v libdrm
 108
 109 Database format
 110 ---------------
 111
 112 Format is produced by libtdb library (http://tdb.samba.org)
 113
 114  key         | value                | meaning
 115 -------------+----------------------+----------------------------------------------------
 116  arch/<arch> | <int>                | number of reports from arch <arch>
 117  ver/<ver>   | <int>                | number of reports from ver <ver>
 118  <name>      | <int><int><int><int> | package <name> was reported <int> times as n,r,v,o
 119
 120 Use popcorn-dump to dump the contents of the database.
 121