jul/design.txt

   1 Lucas Skoeldqvist <frusen@dragora.org>
   2 2016-11-30 rev 1: initial write up
   3
   4 1 INTRODUCTION
   5 ==============
   6
   7 Dragora does have a system for managing packages already (pkgsystem[1] in
   8 Dragora version 2 and qi[2] in version 3). Both of them can build, install,
   9 remove, and upgrade packages, but with limited flexibility; they only work
  10 with local packages on the system. There is no way to search for available
  11 packages, check for upgrades, or fetch packages.
  12
  13 This is where jul comes in. Jul uses the existing package managers and adds
  14 aditional functionality on top. There is a working yet incomplete version
  15 available for use today on Dragora 2.
  16
  17 One can think of pkgsystem/qi as dpkg and jul as apt-get (in Debian) but with
  18 a simpler design.
  19
  20 [1] http://www.dragora.org/repo.fsl/doc/trunk/www/dragora2/guides/pkgmanager.md
  21 [2] http://www.dragora.org/repo.fsl/dir?name=qi
  22
  23 2 DESIGN
  24 ========
  25
  26 Jul is written in Tcl[1] and has a command line interface. The interface is
  27 modeled after Fossil[2] but commands are named similar to that of pkgsystem
  28 and qi. Some examples:
  29
  30         $ jul search foo
  31
  32         $ jul help add
  33
  34         $ jul add -h
  35
  36 [1] https://tcl.tk/
  37 [2] http://fossil-scm.org/
  38
  39 2.1 COMMANDS
  40 ============
  41
  42 The following commands are needed:
  43
  44         1) add/install
  45
  46         2) list
  47
  48         3) search
  49
  50         4) sync/update
  51
  52         5) upgrade
  53
  54         6) help
  55
  56 2.1.1 ADD/INSTALL
  57 =================
  58
  59 These commands do the same thing; adds a package to system. Jul will do a
  60 search for the given package(s) and list the matches. One can then choose from
  61 the list of packages which package(s) to install.
  62
  63 In jul 0.5 you can only add one package at a time, and a list of matches makes
  64 sense. But it is not clear how this would work when multiple packages are
  65 specified on the command line.
  66
  67 2.1.2 LIST
  68 ==========
  69
  70 This command lists installed packages. It can have options to only list
  71 packages from certain repositories (see section 3) or match against a search
  72 term.
  73
  74 2.1.3 SEARCH
  75 ============
  76
  77 `search' takes on or more search-terms and looks for packages. By default it
  78 searches in all enabled repositories but it could take an option to only search
  79 in one or more repositories.
  80
  81 Currently searches in a local copy of the database of available packages. One
  82 might want to do an update simultaneously (see section 4).
  83
  84 2.1.4 SYNC/UPDATE
  85 =================
  86
  87 These commands fetch the latest changes from the repositories.
  88
  89 2.1.5 UPGRADE
  90 =============
  91
  92 `upgrade' compares the installed packages with the ones in the database, and
  93 if they are newer in the database, they can be upgraded.
  94
  95 Some useful options to this commands could be:
  96
  97         1) --list/-l       only list available upgrade, don't prompt to upgrade
  98
  99         2) --onlysec/-o    only list/upgrade packages that are vulnerable
 100
 101 2.1.6 HELP
 102 ==========
 103
 104 The `help' command is used to display help screens. It shows the same help
 105 that the `-h' option does, so these command lines are equivalent:
 106
 107         $ jul help
 108
 109         $ jul -h
 110
 111         $ jul help add
 112
 113         $ jul add -h
 114
 115 3 REPOSITORIES
 116 ==============
 117
 118 A repository is a SQLite[1] database with a few tables. Currently (see section
 119 3.2) it has support for basic package information plus descriptions.
 120
 121 Packages are added to the database and then the database is downloaded by jul
 122 when doing a sync/update. The copy is stored in $HOME/.jul and used by most
 123 commands.
 124
 125 Up until now I've manually (or via scripts) added package information to the
 126 database. It is a lot of work and we need a better and simpler way...
 127
 128 [1] https://sqlite.org/
 129
 130 3.1 GENERATING DATABASES
 131 ========================
 132
 133 Qi introduces `.meta' files, which contain most of the information needed for
 134 an entry in the database. A meta file could look something like this:
 135
 136         name="foo"
 137         version="1.3"
 138         desc="Simple program"
 139         license="GPLv3+"
 140         order="bar zab foo"
 141
 142 If each package has one of these files a database can easily be generated by
 143 parsing these files.
 144
 145 3.2 SQLITE SCHEMA
 146 =================
 147
 148 CREATE TABLE repository (
 149     name text,
 150     url text,
 151     PRIMARY KEY(name)
 152 );
 153 CREATE TABLE description (
 154     name text,
 155     lang text,
 156     desc text,
 157     PRIMARY KEY(name)
 158 );
 159 CREATE TABLE location (
 160     name text,
 161     url text,
 162     PRIMARY KEY(name)
 163 );
 164 CREATE TABLE package (
 165     repo text,
 166     name text,
 167     version text,
 168     arch text,
 169     build integer,
 170     FOREIGN KEY(repo) REFERENCES repository,
 171     FOREIGN KEY(name) REFERENCES description
 172 );
 173
 174 3.3 HOSTING AND SYNCHRONISING
 175 =============================
 176
 177 One hosts a database simply by serving it via HTTP. The database on
 178 gungre.ch is available at: https://gungre.ch/jul/gungre.db
 179
 180 (the databases contain one or more repositories)
 181
 182 Curl[1] is used for fetching so other protocols are supported as well.
 183
 184 Jul supports multiple databases so you could point at dragora.org for the
 185 default repository, gungre.ch for community repositories, and so on.
 186
 187 It would be better if each host could synchronise the other hosts databases and
 188 packages so if one goes down there are other mirrors available.
 189
 190 So each host has a directory tree with packages. The host then runs a script
 191 (see section 3.4) each time packages are added (or using a cron job, or
 192 something) to generate the database.
 193
 194 The hosts will then, maybe twice a day, or every hour, use rsync[2] to fetch
 195 the new version of the database and the new packages.
 196
 197 [1] https://curl.haxx.se/
 198 [2] https://rsync.samba.org/
 199
 200 3.4 VERSION COMPARISON
 201 ======================
 202
 203 The script that generates the databases should only add the latest packages
 204 to the database. To achive this the different versions of a package need to be
 205 compared.
 206
 207 To compare versions we need a specification how to version packages. For
 208 example the author of a package might use the version 1.2-alpha1 and another
 209 author might use the version 2.0a. We need to decide which style to use, to be
 210 able to compare them.
 211
 212 All package managers that does version comparison does this, Gentoo's portage
 213 is not an exception[1].
 214
 215 Besides the specification, some algorithms are needed. I'm currently
 216 translating the algorithms from portage[2].
 217
 218 When the code is written it will be used for jul's `upgrade' command as well.
 219
 220 [1] https://dev.gentoo.org/~ulm/pms/head/pms.html#x1-300003.2
 221 [2] https://dev.gentoo.org/~ulm/pms/head/pms.html#x1-310003.3
 222
 223 4 CONFIGURATION FILES
 224 =====================
 225
 226 The configuration file is just a Tcl script where you can set some variables.
 227
 228 There is a system wide configuration file in `/etc' and a local configuration
 229 file in the users home directory. Like most programs.
 230
 231 Examples of settings:
 232
 233         1) which packages to show (archs)
 234
 235         2) which repositories to use
 236
 237         3) always run the sync/update command before most of the other
 238            commands
 239
 240 Most, if not all, of the settings should be modified via the command line as
 241 options.
 242
 243 5 DISCUSSION
 244 ============
 245
 246 A limited version of jul is available[1,2] today, and a few people in the
 247 community including me use it a lot even if the most exiting features aren't
 248 complete or even missing.
 249
 250 The most pressing thing at the moment is the code for version comparison. I'm
 251 working on it but we need a version specification for it to work. I'm using
 252 portage's version spec. temporarily.
 253
 254 This document was written in somewhat of a hurry and I'm sure things were left
 255 out.
 256
 257 Please discuss on the mailing list and IRC so we have something ready for the
 258 long awaited Dragora 3. :-)
 259
 260 [1] https://gungre.ch/dragora/repo/frusen/stable/jul/
 261 [2] http://dragora.org/repo.fsl/dir?name=jul