slackpkgplus/src/README

slackpkg+ plugin for third-party repositories

Slackpkg is a package manager for Slackware.

Slackpkg+ is a plugin for slackpkg.
   It adds support for third-party repositories.
   You can install, upgrade and search from multiple repositories.

Thanks to alienbob and phenixia2003 for contributing and all other submitted
suggestions and/or patches.

********************* DISCLAIMER **********************
This is NOT an official tool. Use it at your own risk.
The third party repositories are NOT official.
The authors of those repositories are not responsible
for any damage that may be caused to your computer.
*******************************************************

-----


CONFIGURATION

For the basic configuration:

* Edit /etc/slackpkg/slackpkgplus.conf
* Uncomment one or more mirrors and add them to the REPOPLUS list

Note that packages in these repository will not listed if they are present in
the official repositories (see below).

* Optionally, set PKGS_PRIORITY to give priority order for single packages 
  present in multiple repositories or to allow repositories to override
  official slackware packages

For a list of supported repositories see repositories.txt, but you can also
add others yourself.

If you configure repositories that do not support gpg, you may need to set
"CHECKGPG=off" in /etc/slackpkg/slackpkg.conf

Then launch
# slackpkg update gpg
# slackpkg update

To keep slackpkg+ updated, uncomment the 'slackpkgplus' repository, and then
# slackpkg upgrade-all
will upgrade slackpkg+ whenever a new version is released.

-----


MIRRORPLUS

The MIRRORPLUS array defines all mirrors. It accepts these protocols:

1) http/ftp/https: for example,

     MIRRORPLUS['slacky']=http://repository.slacky.eu/slackware64/

   The mirror must contains all metadata files (CHECKSUMS.md5 ...)
   You must run 'slackpkg update' after adding/removing a repository.

2) Local mirror: for example,

     MIRRORPLUS['alienlocal']=file://mirrors/alienbob/x86/14.0/

   The directory must contains all metadata files (CHECKSUMS.md5 ...)
   You must run 'slackpkg update' after adding/removing a repository.

3) Local packages directory: for example,

     MIRRORPLUS['mypackages']=dir://mypackages/

   All packages must be in a single directory (subdirectory not allowed).
   Note that 'slackpkg update' ignores these repositories. Every time you run
   slackpkg, it reads the directory contents.

As mirror name, slackpkg+ accepts numbers, letters, minus and underscore, but
you are encouraged to not use the minus character.

-----


USAGE

See 'man slackpkg' :D

Use the command
# slackpkg upgrade-all
to keep your system up-to-date. This command searches for upgraded packages
spanning all configured repositories.

Use the command
# slackpkg install-new
(if you use Slackware -current) to check for new packages. This command
searches for new packages ONLY in the official Slackware repository.

The command
# slackpkg {install,upgrade,remove,reinstall}
accepts the following kinds of argument:

1) package-name (spanning all repositories), for example
   # slackpkg install bsd-games

2) part of package-name (spanning all repositories), for example
   # slackpkg install alsa

3) path of packages in repository (spanning all repositories), for example
   # slackpkg install xap

4) repository-name, for example
   # slackpkg upgrade alienbob
   upgrades all packages in the alienbob repository, and
   # slackpkg install ktown
   installs all packages in the ktown repository

5) repository-name:package-name, for example
   # slackpkg install slacky:openjdk
   installs openjdk from slacky even if there is another openjdk in another
   repository

6) file:local-file-name (txz/tgz), for example
   # slackpkg install file:mypackage-1.0-noarch-1my.txz
   installs mypackage even though not defined in slackpkgplus.conf
   (you can specify either a relative or an absolute path)

7) dir:directory, for example
   # slackpkg {install|upgrade} dir:/root/myrepo
   installs or upgrades all packages in /root/myrepo/
   (The final '/' is not strictly required.)
   Note: 'slackpkg install .' is an alias of 'slackpkg install dir:./', but
   'slackpkg install ./' is NOT the same alias; see FILE in man slackpkg

-----


PRIORITY CONFIGURATION

When a package is present in more than one repository, the package will be
searched for in the following order:

1) as listed in PKGS_PRIORITY (allow to override official packages)
2) as listed in an official Slackware repository
   (configured in /etc/slackpkg/mirrors)
3) as listed in REPOPLUS (deny to override official packages)
4) all others defined in MIRRORPLUS

PKGS_PRIORITY syntax:
  PKGS_PRIORITY=( <repository name>:<package name> ... )

for example:
  PKGS_PRIORITY=( alienbob:openjdk )

<package name> accepts a regular expression, so for example
  PKGS_PRIORITY=( restricted:.* vlc.* )
means 'all packages containing the "vlc" string'
  PKGS_PRIORITY=( ktown:.* )
means 'all packages in repository ktown'

latest item maybe replaced simply with
  PKGS_PRIORITY=( ktown )

all packages matched from ktown ovverride all related slackware packages, unless
you do not explicitly exclude it:
  PKGS_PRIORITY=( patches:harfbuzz slackware64:harfbuzz ktown )
that means 'all ktown packages except harfbuzz'


Also you can set TAG_PRIORITY=on to allow slackpkg+ to select repository
from where the package was previously installed.
This method is based from tag of the installed package.
slackpkg+ search a package with the same tag in all repositories and use it.
If two repositories contains the same tag, it will honour REPOPLUS.
 

-----


MULTILIB

If you want to use a multilib system, you can automatically configure the
multilib repository in slackpkgplus.conf and install multilib simply by running:
# /usr/doc/slackpkg+-*/setupmultilib.sh

To configure multilib manually (e.g. if you have installed multilib already),
uncomment the correct "MIRRORPLUS['multilib']=...",
and uncomment "PKGS_PRIORITY=( multilib:.* )".
If you do not plan to build yourself 32bit packages on your 64bit machine, you may
avoid to install gcc:

   PKGS_PRIORITY=( patches:gcc slackware64:gcc multilib )


To install multilib manually, launch:
# slackpkg update gpg
# slackpkg update
# slackpkg upgrade-all
# slackpkg install multilib

After that, you can keep multilib up-to-date by launching:
# slackpkg update
# slackpkg upgrade-all
and re-running 'slackpkg install multilib' if 'slackpkg install-new' has found
any new packages.

To uninstall multilib, you must remove 'multilib:.*' from PKGS_PRIORITY and from
REPOPLUS, but do NOT delete the related MIRRORPLUS line, then launch:
# slackpkg update
# slackpkg remove multilib
Note: this does NOT remove the core multilib packages, because they affect the
64bit system. You must remove these by launching:
# slackpkg upgrade-all
then delete or comment the related MIRRORPLUS line, and finally launch
# slackpkg update

or just re-run
# /usr/doc/slackpkg+-*/setupmultilib.sh


-----


KTOWN (LATEST KDE)

If you want to install the latest KDE packages from AlienBOB's ktown repository
(currently kde 4.14.3 in slackware 14.1 and kde 5.15.7 in slackware current),
add "PKGS_PRIORITY=( ktown )"
# slackpkg update gpg
# slackpkg update

To install ktown you need some attention, so please refeer to official
documentation for details:
http://alien.slackbook.org/ktown/14.1/latest/ (kde 4)
http://alien.slackbook.org/ktown/current/5/   (kde 5)

* ktown4 on slackware 14.1:

slackpkg install ktown
slackpkg upgrade-all
slackpkg remove kdeadmin kdenetwork kdesdk kdetoys kwallet kdnssd
slackpkg clean-system

* ktown5 on slackware current:

slackpkg remove libkscreen kscreen kactivities kde-workspace libmm-qt libnm-qt plasma-nm polkit-kde-agent-1 polkit-kde-kcmodules-1 kdeconnect-kde
slackpkg install ktown
slackpkg upgrade-all
slackpkg clean-system

if you are upgrading an already installed ktown5, you may also need
slackpkg reinstall ktown
BEFORE slackpkg install ktown


Note - for both ktown4 and ktown5 - that the packages to remove may change in newer version of ktown (at moment are kde-4.14.3 and kde-5_15.11), so I encourage to read linked documents BEFORE install it.


After that, you can keep the ktown KDE up-to-date by launching:
# slackpkg update
# slackpkg upgrade-all
Periodically you should re-run
# slackpkg install ktown

To restore the Slackware KDE, remove all 'ktown' referall in config file, then launch:
# slackpkg update
# slackpkg reinstall kde
# slackpkg install kde
# slackpkg upgrade-all
# slackpkg clean-system ktown
# slackpkg update


-----


PERSONAL PACKAGES

If you build some packages yourself, you can install these without
installpkg, by using slackpkg+. This helps you to track the install/upgrade,
and reduces the possibility of errors. You do NOT need to create a personal
repository with a gpg-key and metadata every time you build a package; also
you do NOT need to modify your slackpkgplus.conf file or launch 'slackpkg
update'.

You can:

1) install/upgrade/reinstall a single package by passing the full file name
   (optionally with absolute or relative path), for example
   # slackpkg install file:package-1.0-noarch-1my.txz
   or
   # slackpkg upgrade file:../repo/package-2.0-noarch-1my.txz

2) install/upgrade/reinstall all packages in a single directory (but not in a
   subtree) by passing a directory name (optionally with absolute or relative
   path), for example
   # slackpkg install dir:/myrep
   or
   # slackpkg upgrade dir:./test/package/
   or
   # slackpkg reinstall .

   Note: '.' is an alias of 'dir:./', but only that alias exists.
   'slackpkg install ./' (or /myrepo/ or ./package.txz) generates an error,
   because in standard slackpkg you can specify a FILE as input, so in
   'slackpkg install ./list.txt' list.txt must be a plain file containing a list
   of packages to install (see man slackpkg)

   If a directory contains the same package with two different versions,
   slackpkg shows the 'alphabetically' highest, so pkg-9.1 will be listed
   instead of pkg-8, but pkg-9 will be listed instead of pkg-10.
   Sorry... this is a slackpkg limitation!

   Tip: if you want to use dir:/myrepo to track your installations and you have
   lost the original txz/tgz file, you can simply create an empty file; this
   fools slackpkg+, which only searches for file name and not for contents
   (unless you run slackpkg reinstall on these packages ;))  So, by doing
   # touch mypkg1-1.0-noarch-1my.tgz
   # touch mysecondpkg-1.1-noarch-2my.txz
   (where mypkg1 and mysecondpkg are already installed packages),
   'slackpkg install .' (or upgrade) does not show you those packages, but
   'slackpkg reinstall .' DOES show them (so do not continue the installation)

NOTE: slackpkg+ will skip the gpg and md5 check for personal packages!!

-----


REMOTE PACKAGES WITHOUT METADATA

Some users share packages on their personal sites, but do not create metadata
files (particularly if they share only a few packages). To install one of these
packages, you could download it and install it manually. But now with slackpkg+
you can specify a direct URL for the package that will automatically download
and install/upgrade the package.

You can:

1) install/upgrade/reinstall a single package by specifying the complete url:
   # slackpkg install http://site/path/package-1.0-noarch-1my.txz
   For example, you may use this function to install a snapshot of slackpkg+
   (that is not available with 'slackpkg upgrade slackpkg+' because it is a beta
   version):
   # slackpkg upgrade http://www.slakfinder.org/slackpkg+/pkg/slackpkg+-20130905.2-noarch-1mt.txz

2) install/upgrade/reinstall all packages in a single remote directory (but not
   in a subtree) even if the site owner does not create metadata:
   # slackpkg install http://site/path/

   Note: this function requires lftp and may fail if the server does not support
   Directory Listing or if there is a index.html in the path.

NOTE: slackpkg+ will skip the gpg and md5 check for remote packages without
metadata!!

------


NOTIFICATIONS

Some package require special post-installation activity as upgrading a related
package or rebuilt kernel modules or change a custom configuration. A user may
forgot to do this, especially in large updates. The notification functionality
help the user to remember it. In /etc/slackpkg/notifymsg.conf you can define
some custom event. See documentation in that file. Events may be VERY custom
(on kde upgrde remember me to call my friends ;), or the more useful 
"on kernel upgrade remember to recompile all driver modules"

You may enable this function by setting "ENABLENOTIFY=on" in slackpkgplus.conf


-----

WGET Options

slackpkg+ uses wget to download packages and metadata.

You can use the WGETOPTS setting to pass options to wget.

By default when an url is unreachable wget - after a long timeout - retry to
download so if a repository is unreacheble you should remove it from your
configuration file.
As workaround you can add the options WGETOPTS="--timeout=5 --tries=1"
in slackpkgplus.conf

-----

DOWNLOADCMD Option

You can choose to use an alternative to wget.

Note that downloader will be called as
$DOWNLOADCMD destinationfile url

The base is
DOWNLOADCMD="wget -O"
by default slackpkgplus adds other useful options:
DOWNLOADCMD="wget $WGETOPTS -nv --no-check-certificate --passive-ftp -O"

If you like curl:
DOWNLOADCMD="curl -o"
you can add other options BEFORE the last '-o' switch:
DOWNLOADCMD="curl -v -o"

If you want use a multi-connection (parallel) download, you can install aria2
(http://aria2.sourceforge.net/) and set
DOWNLOADCMD="aria2c -x 16 -s 16 --auto-file-renaming=false --allow-overwrite=true -d / -o"
if you have proxy add
DOWNLOADCMD="aria2c --all-proxy=someproxy:8080 -x 16 -s 16 --auto-file-renaming=false --allow-overwrite=true -d / -o"

-----

CACHEUPDATE Option

By default 'slackpkg update' download all metadata files (CHECKSUMS.md5, PACKAGES.TXT,
MANIFEST.bz2). When you use many and or large repositories, this may take a lot of
time and in most cases there are no news or news just in only one repository.

Enabling CACHEUPDATE slackpkg+ put a cache of metadatas in /var/lib/slackpkg/cache,
so everytime it just must to verify if there is a new version, otherwise it can use
the cached file.

Note that it works only with http repositories and does not work with proxies.
It uses 'curl' to download file headers to check if there is a new version of
the file.

Set CACHEUPDATE=on to enable it. Default is 'off'


-----

DOWNLOADONLY Option

Sometimes may be useful to just download only the packages, and in a second moment 
install it. For example for large upgrades I can download all in the night while 
I sleep and then install all in the morning.

Also it is good when the 'install-new' give you a large list of packages to install.

You can set DOWNLOANDONLY=on in slackpkgplus.conf to do that or use it in cmdline.

For example, to upgrading from slackware 14.1 to slackware 14.2:
# DOWNLOADONLY=on slackpkg install-new
# DOWNLOADONLY=on slackpkg upgrade-all
# slackpkg install-new
# slackpkg upgrade-all
# slackpkg clean-system

-----

ALLOW32BIT

By default slackpkg+ deny to install 32bit packages on a 64bit system.

Set ALLOW32BIT=on to allow slackpkg+ to install 32bit packages on a 64bit slackware 
installation (possibly unsafe). Please, do not install both 32 and 64bit of the same 
package to avoid problems, and NEVER upgrade exitant 64bit packages with relative 32bit
package.

Do not forget to install the multilibs.


-----

GREYLIST

Sometime you may want that slackpkg+ does not install some package in the upgrade-all
process. To do that you must uncheck the package everytime or add it in the
'blacklist' file. The first method may be onerous when you use upgrade-all frequently.
The second method does not allow you to know which package version is available.
A thirdy method is to put it in the 'greylist' file.
All packages listed in greylist will be available to install and listed in slackpkg
dialog, but they will be unchecked by default so you are sure to not install it
wrongly.
You may decide also to greylist one entire repository. A good idea is to greylist
all thirdy party repository so an upgrade-all automatically upgrade official
slackware packages but force you to review all other packages so to be sure on what
you install.

-----

SENSITIVE_SEARCH

By default the 'slackpkg search' and 'slackpkg file-search' do case sensitive
searches, so 'slackpkg search mplayer' does NOT find the slackware package 
MPlayer-1.1_20130819-x86_64-2

You can search case-insensitive by setting SENSITIVE_SEARCH to off in config file.
You can also do temporary case-insensitive searches overriding that setting in cmdline

SENSITIVE_SEARCH=off slackpkg search mplayer


Note tha 'slackpkg install' still remains case sensitive, so you must use
slackpkg install MPlayer

WARNING: do NOT run 'slackpkg search slackpkg' with SENSITIVE_SEARCH=on. It
may take a very lot of time!

-----

WW_FILE_SEARCH

By default 'slackpkg file-search' search whole words, so 
# slackpkg file-search slackpkgpl
returns nothing.

By setting WW_FILE_SEARCH to on, the same command should find slackpkg+
becouse match slackpkgplus.conf and other.

Note that a short pattern may match many many packages.

-----

SHOWORDER

By default slackpkg in dialogbox sort packages by name.
For large upgrades from many reporitories, may be useful sorting by repository name.
With this option you can sort packages by package name, repository, tag, path
(in the repository), architecture:

# Select the show order in dialogbox. Available "package" "repository" "tag" "path" "arch"
SHOWORDER=repository

Default is "package"

-----

DETAILED_INFO

By default, "slackpkg info <package>" show the metadata and the package
description.
This is the same if you select DETAILED_INFO=none

DETAILED_INFO=basic show the repository on the repository, and the url to 
download it.

DETAILED_INFO=filelist alo show the full file list of the package.

-----

STRICTGPG

slackpkg was bird to install slackware packages from official mirrors; they
are signed with the official slackware GPG-KEY, so no other packages may be
added (unless you disable GPG check).
slackpkg+ introduces the ability to download keys from many repositories; as
implication, slackpkg+ allow also to copy packages from other repositories and
the original signature; in this way a repository can contain a mix of packages
that may confuse the user.

Strict GPG check disallow users to do that. This improve the security.

However some user may want to do a custom repository with any type of
packages.
To use a similar repository you may set STRICTGPG=off
Note that sometime you may need to import manually the GPG-KEY with the command
# gpg --import GPG-KEY

Note: after upgrading from slackpkg+ <= 1.7, you must run slackpkg update gpg.
Also you need it everytime you add or rename a reporitory in
slackpkgplus.conf.

-----

INSTALL LOG

Slackpkg+ now create a log of all installed packages in /var/lib/slackpkg/install.log
and try to add in this log from which repository you have downloaded the file.
This help you to track your slackware installation.

You are encouraged to run '/usr/lib/slackpkg/makeinstlog.sh -t' (this may take a few)
to initialize the log (it will create /var/lib/slackpkg/install.log.tmp). The '-t' 
param add the repository name from which the packages was downloaded, but it may fails,
so you are encouraged to review the file before rename it in install.log.
Note that you can edit manually to modify or add informations.

At every slackpkg install/upgrade/remove invocation, a new log will be added.
At every slackpkg update invocation, a fast list rebuild will be done.

-----

CHECK-UPDATE IMPROVEMENT

the command "slackpkg check-updates" reports the repositories which have been changed since
the last update. For more details and some suggests how to use it in crontab see:
http://www.linuxquestions.org/questions/showthread.php?p=5146591

-----

SEARCH FUNCTION IMPROVEMENT

The command "slackpkg search ..." when finds two packages with the same name
but with different versions, it will show all so you know all repositories
that contains that package, not just the first in priority list.
It will mark all versions not in priority (i.e. that install/upgrade will not
show) as 'masked'. To install that packages you must explicitly specify the
repository name with "slackpkg install/upgrade repository:package".

-----

FURTHER INFORMATION

The AlienBOB article about slackpkg+:
  http://alien.slackbook.org/blog/introducing-slackpkg-an-extension-to-slackpkg-for-3rd-party-repositories/

For questions, suggestions or contributions, you can email me at
zerouno@slacky.it or use the linuxquestions forum:
  http://www.linuxquestions.org/questions/showthread.php?p=4940074

You can find slackpkg+ on sourceforge:
  https://sourceforge.net/projects/slackpkgplus