Source

kalu / kalu.pod

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
=head1 NAME

kalu - Keeping Arch Linux Up-to-date

=head1 SYNOPSIS

B<kalu> [I<OPTION>...]

=head1 OPTIONS

=over

=item B<-a, --auto-checks>

Run automatic checks (no GUI, see L<B<NOTES>|/NOTES> below)

=item B<-m, --manual-checks>

Run manual checks (no GUI, see L<B<NOTES>|/NOTES> below)

=item B<-d, --debug>

Enable debug mode. Debugging messages will then be sent to kalu's stdout,
prefixed with a timestamp.

=item B<-V, --version>

Show version information and exit

=item B<-h, --help>

Show a little help text and exit

=back

=head1 DESCRIPTION

B<kalu> is (yet another) upgrade notifier for Arch Linux. Once started, it
will add an icon into your systray, and regularly check if any upgrade is
available, and if so show a notification to inform you about it.

You can know whether anything was found during kalu's last check or not by
its icon: if gray nothing was found. If blue, you can mouse over it to see (in
the tooltip) what was found.

If the icon happens to blink from gray to blue, it means kalu is currently busy.

kalu can check for a few things, each one resulting in a separate
notification (if something is found) :

=over

=item B<* Upgrades>

kalu will check for upgrades of any of the installed packages, similarly to
what a `pacman -Syu` would do. To do so, kalu does not requires root
privileges to do its checking. In order to determine whether or not upgrades
are available, it will create a temporary copy of your sync databases and
synchronize those copies, and of course remove them once done.

That way not only can all this be done as user, but it avoids putting you
in a situation where you'd risk messing up your system, as you might otherwise
unknowingly end up basically doing a `pacman -Sy foobar` (which is pretty
generally understood to be a bad idea).

(Because if your databases were synchronized and upgrades were available,
yet you did not upgrade right away - e.g. because you didn't see the
notification or were busy on something - then your next -S operation would
really be a -Sy even though you might not even realize it.)

=item B<* Watched packages>

kalu will check for upgrades of packages that aren't currently installed.
This is done by simply maintaining a list of packages (name & version) and
checking it against the online repos (after synchronization).

When upgrades are available, you will be able to easily "mark them" - i.e.
kalu can auto-update the list with the latest version number. You will of
course be able to select which of the packages to update, if any.

If so, and a newer version is available, you will be notified. If you have
foreign packages which you know are not in the AUR (and therefore checking
for them is useless), you can put them on an ignore list, see L<B<PREFERENCES>|/PREFERENCES>
below.

=item B<* AUR packages>

kalu will compile the list of foreign packages on the system (i.e. not found
in any repo, or what you'd have from running `pacman -Qm`) and check to see
if they are available in the AUR. If so, it will check whether the AUR
version is more recent than the one installed.

=item B<* Watched AUR packages>

Just as with "official" packages, you can maintain a list of non-installed
packages that kalu should check the AUR for.

=item B<* Arch Linux News>

kalu will check the news from the Arch Linux website (L<http://www.archlinux.org>)
and show a notification whenever something new has been posted.

The notification can only feature titles, but using the button "Show news"
will show the complete news. Note that this is done through kalu's own
rendering (i.e. there is no HTML engine used) and as such the rendering
might differ.
For example, images are not supported.

Links are processed through B<xdg-open(1)> to be opened in your default browser.

=back

=head1 DATA LOCATION

Every setting/data kalu stores will be done in folder F<~/.config/kalu/> which
can contain the following files :

=over

=item - I<kalu.conf> : your preferences

=item - I<watched.conf> : the list of watched packages

=item - I<watched-aur.conf> : the list of watched AUR packages

=item - I<news.conf> : information about which news you have already read

=back

=head1 PREFERENCES

Preferences are presented under a few tabs. Most of those represent a type of
check/notification supported by kalu, and as such include a template definition
allowing you to tweak the content of said notifications.

The only required template is I<Upgrades>. All others, or more specifically,
each of their fields, are optional.

If a field is not defined, kalu will simply fall back and use the corresponding
field from the I<Upgrades> template. One exception: the template I<Watched AUR>
will fall back to the I<AUR> template, and only if nothing was defined there will
I<Upgrades> be used.

All templates are made of 3 fields: Title, Package (or News item), and Separator.
B<Title> will be the title of the notification. B<Package> (B<News item>) is the
text corresponding to one package/news item. It will be repeated for each
package/news item, separated using B<Separator>, to make the body of the
notification.

Each field can have none, one or more variables. They are not the same for all
templates, so they'll be described in each of them below.

In addition to \n for a new line, you can use some markup tags, but only in
the body of the notification (i.e. in the fields B<Package/News item> and
B<Separator> but not in B<Title>), such as <b> ... </b> for bold, <i> ... </i> for
italic or <u> ... </u> for underline.

Note that though support is recommanded, whether or not those will actually be
applied on the notifications depends on your notification daemon.

Preferences are presented under the following tabs :

=head2 General

=over

=item I<Configuration file (pacman.conf)>

This is the configuration file used to initialize the Arch Linux Package
Management (ALPM) library (whose most famous front end is no other than
pacman).

=item I<Icon used on notifications>

Specify the icon to be used on notifications. Can be none, kalu's icon (small)
or selecting a file to load it from.

When loading icon from a file, the icon will be used "full size" so you can use
a small or a large one, as you like. E.g. using F</usr/share/pixmaps/kalu.png>
will use kalu's icon at its full (48x48) size.

If loading the icon fails, kalu will silently fall back to using it own icon
(small).

=item I<Notifications expire after (seconds)>

The delay after which the notification should expire/be automatically
closed by the daemon. The left-most value will use the default (from
the daemon), while the right-most value will set notifications to never
expires, i.e. they will stay opened until either you manually close them,
or for notifications with an action button until kalu is closed.

=item I<Check for upgrades every (minutes)>

How often must kalu run its automatic check. Select from the list, or
type in what you want.

=item I<Do not check between .. and ..>

This is e.g. in case you keep your computer on 24/7, yet go to sleep at
some point. It would then make sense that you not want kalu to do its
checks while you're sleeping.

Specify here the period during which no (automatic) checks will be
performed (Of course, you can always ask for one manually).

=item I<During an automatic check, check for ..>

Select one or more checks that will be performed during every automatic
check, i.e. run on start or at the interval specified above.

=item I<During a manual check, check for ..>

Select one or more checks that will be performed when you start a manual
check, i.e. using menu "Check for Upgrades"

=back

=head2 News

=over

=item I<Notification template>

=over

=item Title

=over

=item B<$NB>   : number of news items

=back

=item News item

=over

=item B<$NEWS> : the title of the news

=back

=item Separator

No variables available.

=back

=back

=head2 Upgrades

=over

=item I<Check for pacman/kalu conflict>

When showing the notification, kalu will check if there's an upgrade of pacman
likely to prevent the system upgrade due to kalu's dependency to the current
version of pacman (i.e. due to API changes in libalpm).

If so, a button will be featured on the notification, to show a little message
about the reason for such a conflict, and how to perform the system upgrade.

=item I<Show a button "Upgrade system" on notifications (and on kalu's menu)>

Whether or not notifications should feature a button "Upgrade system" and
kalu's menu (right-click on its systray icon) feature an item "System upgrade"

=item I<When clicking the button>

Clicking the button can either start kalu's own updater (see L<B<PREFERENCES>|/PREFERENCES>
below), or simply run the program of your choice.

=item I<Command-line>

The command line to start when pressing the button "Upgrade system" from the
notification.

=item I<After completing a system upgrade, ask whether to start the following>

When using kalu's updater, you can define one or more processes to be ran after
a system upgrade was completed. Specify their command-line in the list, and
they'll be started after a succesful system upgrade.

You can use B<$PACKAGES> in the command line, which will be replaced by the
list of all packages involved in the sysupgrade (i.e. packages upgraded, as well
as those added or removed, for instance when a package is replaced by another one).

=item I<Ask confirmation before starting anything>

If enabled, a confirmation will be asked before any process is started after the
sysupgrade. In case you specify more than one, the full list will be featured
and you will be able to determine which (if any) to start each time.

=item I<Notification template>

=over

=item Title

=over

=item B<$NB>  : the number of packages

=item B<$DL>  : the total download size

=item B<$INS> : the total installed size

=item B<$NET> : the total net (post-install difference) size

=back

=item Package

=over

=item B<$PKG> : the name of the package

=item B<$OLD> : the version number of the currently installed version

=item B<$NET> : the version number of the version available in the repo

=item B<$DL>  : the download size

=item B<$INS> : the installed size

=item B<$NET> : the net (post-install difference) size

=back

=item Separator

No variables available.

=back

=back

=head2 Watched

=over

=item I<Manage watched packages>

Does the same as the menu by the same name, that is open the window to manage
(add, edit, remove) the list of watched packages. This list is independent from
the preferences, as data are saved in a different file, as saving the list will
not have an effect on preferences, and vice versa.

=item I<Notification template>

=over

=item Title

=over

=item B<$NB>  : the number of packages

=item B<$DL>  : the total download size

=item B<$INS> : the total installed size

=item B<$NET> : the total net (post-install difference) size

=back

=item Package

=over

=item B<$PKG> : the name of the package

=item B<$OLD> : the version number from the list of watched packages

=item B<$NET> : the version number of the version available in the repo

=item B<$DL>  : the download size

=item B<$INS> : the installed size

=item B<$NET> : the net (post-install difference) size

=back

=item Separator

No variables available.

=back

=back

=head2 AUR

=over

=item I<Show a button "Update AUR packages" on notifications>

If enabled, notifications for AUR packages will feature a button "Update AUR
packages" which will start the specified command-line. If not, no button will
be featured.

=item I<When clicking the button, run the following>

The command line to start when pressing the button "Update AUR packages" from the
notification.

You can use B<$PACKAGES> in the command line, which will be replaced by the
list of all packages for which an upgrade is available in the AUR.

=item I<Do not check the AUR for the following packages>

By default kalu determines the list of all foreign packages (i.e. not found
in any repo, or what you'd have from running `pacman -Qm`) and check to see
if they are available in the AUR.

If you have packages which you know are not there (or simply for which you do
not want to be notified), simply add their names to this list.

=item I<Notification template>

=over

=item Title

=over

=item B<$NB>  : the number of packages

=back

=item Package

=over

=item B<$PKG> : the name of the package

=item B<$OLD> : the version number of the currently installed version

=item B<$NET> : the version number of the version available in the AUR

=back

=item Separator

No variables available.

=back

=back

=head2 Watched AUR

=over

=item I<Manage watched AUR packages>

Does the same as the menu by the same name, that is open the window to manage
(add, edit, remove) the list of watched AUR packages. This list is independent
from the preferences, as data are saved in a different file, as saving the list
will not have an effect on preferences, and vice versa.

=item I<Notification template>

=over

=item Title

=over

=item B<$NB>  : the number of packages

=back

=item Package

=over

=item B<$PKG> : the name of the package

=item B<$OLD> : the version number from the list of watched AUR packages

=item B<$NET> : the version number of the version available in the AUR

=back

=item Separator

No variables available.

=back

=back

=head2 Misc

=over

=item I<Use sane indicator>

Because in the Linux world, when a list is ordered descendingly, the arrow points...
up!? This option restores sanity and have it point down.

This is used when sorting packages in kalu's updater.

=item I<Show if databases can be synchronized in tooltip>

An indication of how many databases can by synchronized (i.e. are not up-to-date)
will be featured on the tooltip, regardless of whether upgrades are available or
not.

=item I<When (double) clicking the systray icon>

Defines the action to be done when you single/double click on kalu's systray icon.

=over

=item B<* Do nothing>

Does exactly that

=item B<* Check for Upgrades>

Start a manual check

=item B<* System Upgrade>

Start a system upgrade. This will do the same as using menu "System Upgrade" or
the button "Upgrade system" on notification; i.e. the specified action done
depends on your settings under B<Upgrades>

Note that if no button "Upgrade system" is shown on notification, this option
will have the same effect as B<Do nothing>

=item B<* Hide/show opened windows (except kalu's updater)>

Will hide all opened windows (except for kalu's updater). If at least one
window is hidden, an indication will be featured on the tooltip (" +" next to
"kalu") and triggering the action again will then show all hidden windows.

=back

=item I<Command line to open links (in news)>

The command line to be executed when a link (on news) is clicked. Use variable
B<$URL> as placeholder for the full URL to be opened.

=back

=head1 SYSTEM UPGRADE

An item "System Upgrade" on kalu's menu, as well as a button "Upgrade system"
on notifications for available upgrades, can be featured. This button can start
a process of your choice, or kalu's own system upgrader. (See L<B<PREFERENCES>|PREFERENCES>
above.)

The later will first synchronize your databases, then upgrade all packages that
are out of date. In other words, it does what a `pacman -Syu` would do, only
in a GTK GUI.

In order to synchronize databases and upgrades packages, root privileges are
obviously required. The way this is handled is as follows: kalu itself only
contains the GUI, and therefore can work running under your (user) account.

The part that does interact with libalpm (to actually synchronize databases and
upgrade packages) is in a secondary library (I<kalu-dbus>), that is the only
one to require root privileges.

This binary will be executed automatically, with root privileges, through DBus
when needed, and PolicyKit will be used to ensure that you are authorized to
upgrade the system.

When upgrading your system with kalu's updater, your log file (e.g. pacman.log,
as defined in pacman.conf) will be updated. kalu adds an entry for each
database synchronized, one when starting the upgrade, one after the upgrade
was completed, and one after each package operation (installed, upgraded,
removed).

This is all very much like pacman itself, only all those will be prefixed with
I<kalu:> so that you can identify them easily. Note however that other log
entries added during an upgrade with kalu's updater might not have such prefix,
specifically all those coming from libalpm directly, such as warnings, errors
or scriptlet output.

=head1 NOTES

Command-line options B<--auto-checks> and B<--manual-checks> both work without
any need for GUI. This means any and all output will be show on stdout/stderr,
and there is no need for a DISPLAY to be available.

In other words, you can run kalu using those options from a tty or through SSH,
and it will work fine. You can also use kalu in a script that way.

Note that GTK+ and other dependencies are obviously still required, although
there is a I<configure> option available to disable all GUI completely during
compilation, in order to produce a CLI version of kalu.

=head1 BUGS

They're probably crawling somewhere in there... if you happen to catch one,
(or more) report it and I'll do my best to squash it.

=head1 REPOSITORY

You can find the latest source code of B<kalu> as well as report bugs and/or
suggest features on its BitBucket repository, available at L<https://bitbucket.org/jjacky/kalu>

=head1 AUTHORS

=over

=item Olivier Brunel <i.am.jack.mail AT gmail DOT com>

=item Dave Gamble

=item Pacman Development Team <pacman-dev AT archlinux DOT org>

=back

=head1 ARTWORK

Icon by Painless Rob (L<https://bbs.archlinux.org/viewtopic.php?id=130839>)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.