EPKG Package Manager

Epkg Package Manager

First of all, the holy epkg --help.

epkg runs as root, so use it from a root shell or with sudo. Only epkg search works as a normal user (and a few of the experimental binary commands, see at the end).

Almost every command has an auto twin that does the same thing without asking for confirmation, and the most used commands have a short alias, written next to them on this page (for example epkg i is epkg install). They do exactly the same thing, use whichever you like.

If your system is on avasile --srcmode (full Gentoo mode), epkg refuses to run. Use emerge directly, or switch back with avasile --usermode or avasile --devmode.

To install packages

epkg install <package> or epkg i <package>

No confirmation:

epkg autoinstall <package> or epkg ai <package>

If you want to install something without adding it to your world file (for example a one time dependency):

epkg oneshot <package> or epkg o <package>

No confirmation:

epkg autooneshot <package> or epkg ao <package>

To search for packages

epkg search <package> or epkg s <package>

To remove packages

epkg remove <package> or epkg r <package>

No confirmation:

epkg autoremove <package> or epkg ar <package>

This is the safe way: the package is removed only if nothing else installed still needs it.

If you really know what you are doing and want it gone no matter what depends on it:

epkg forceremove <package>

No confirmation:

epkg autoforceremove <package>

This can break your system, use it only when epkg remove refuses and you understand why.

To update

epkg update or epkg u

This syncs the Gentoo portage tree, the argent-ws overlay and the Argent portage configuration, and refreshes the keys used to verify binary packages.

There is no epkg autoupdate, epkg update never asks anything.

If the repositories take too much space on your disk, you can also compact their git history:

epkg update --clean or epkg u --clean

If epkg update takes too long, you can:

cd /etc/portage && git pull && cd /var/db/repos/gentoo && git pull && cd /var/db/repos/argent-ws && git pull && git submodule update --init --recursive --depth=1

To upgrade

epkg upgrade or epkg ug

No confirmation:

epkg autoupgrade or epkg aug

After every upgrade run etc-update and accept the configuration changes that come from Argent.

At the end of a successful epkg upgrade or epkg upgrade-full, epkg updates the package index (emaint binhost -f) and shows:

Updating the package index, this can take a while. Please wait...

With a lot of packages this can take a long time. It is not stuck, let it finish.

To upgrade only some packages:

epkg upgrade-specific <package>

No confirmation:

epkg autoupgrade-specific <package>

Oneliner command to do both update and upgrade:

epkg update && epkg upgrade

To clean after upgrade/install

epkg clean or epkg c

No confirmation:

epkg autoclean or epkg ac

Both also remove the outdated local binary packages (see Local binary packages when cleaning). epkg clean shows you the list and asks first, epkg autoclean removes them without asking.

To upgrade also development & build packages

epkg upgrade-full or epkg ugf

No confirmation:

epkg autoupgrade-full or epkg augf

For development, you can pass extra emerge options at the end:

epkg upgrade-full --complete-graph y --keep-going y

• --complete-graph y checks the whole dependency graph, not only the packages that get upgraded, so broken dependencies of your installed packages show up before anything is merged.
• --keep-going y does not stop at the first package that fails to compile: it continues with everything that does not depend on it, and lists the failed ones at the end.

Local binary packages when cleaning

Upgrades do not remove any binary package. That is done by epkg clean and epkg autoclean: after removing the unneeded packages, they run eclean-pkg and remove the outdated binary packages from PKGDIR and /var/cache/binhost/, same as epkg cleanoutdated, then update the package index.

• epkg clean first shows which packages would be removed and how much space they take, then asks. If you answer no, nothing is removed.
• epkg autoclean removes them without asking.

To keep the local binary packages, set EPKG_BACKUP_PKG="1". EPKG_BACKUP_PKG="0", or not setting it at all, keeps the cleanup on.

For one clean only:

EPKG_BACKUP_PKG=1 epkg clean

For good, put EPKG_BACKUP_PKG="1" in /etc/portage/make.conf.local or in any file inside /etc/portage/make.conf/, for example /etc/portage/make.conf/99-persona.conf.

If it is set in more than one place, epkg uses the first it finds:

1. the command line (EPKG_BACKUP_PKG=1 epkg clean)
2. /etc/portage/make.conf.local
3. the files in /etc/portage/make.conf/

Portage reads the files in /etc/portage/make.conf/ in alphabetical order and the last one wins. If 00-main.conf has "0" and 01-persona.conf has "1", the packages are kept, but a later 02-something.conf with "0" turns the cleanup back on. To be sure your setting wins, give the file a high number, like 99-.

Check before you do it, or update before you do it

The interactive commands (install, remove, upgrade, upgrade-full, clean, ...) accept --check as the first argument. epkg then tells you if your repositories are older than the Argent servers before it starts:

epkg upgrade --check

The no confirmation commands (autoinstall, autoremove, autoupgrade, autoupgrade-full, autoclean, ...) accept --update as the first argument, and run an epkg update first:

epkg autoupgrade --update

When something goes wrong

If an install or upgrade failed in the middle and you fixed the reason, continue from where it stopped:

epkg resume

If a merge was killed (power loss, closed terminal, Ctrl+C at the wrong moment), or epkg update keeps failing:

epkg fix

It shows the interrupted merges left in /var/db/pkg and asks you if you want them removed, then verifies the portage tree and the argent-ws overlay and downloads again the ones that are damaged.

epkg fix --force

Careful: with --force it removes the interrupted merges without asking, and it downloads again both repositories from scratch, even if they are healthy.

If binary packages are refused because of their signature:

epkg regen-keys

If an upgrade ends with:

!!! Problems have been detected with your world file

!!! Please run emaint --check world

!!! Ebuilds for the following packages are either all masked or don't exist:

it is a warning, not an error. Your world file (/var/lib/portage/world) is the list of packages you asked for yourself. Some of them are no longer in any repository you have: they were removed from Argent or Gentoo, their overlay was removed, or they are masked now. Old kernel slots (sys-kernel/gentoo-sources:6.5.12) and packages that were dropped long ago (net-im/skypeforlinux) are the usual ones. They stay installed, but they cannot be upgraded or reinstalled anymore.

To see what is wrong in the world file:

emaint --check world

It lists the entries that are not valid and the entries that are not installed anymore. To remove exactly those from the world file (nothing gets uninstalled):

emaint --fix world

For the packages that are still installed but have no ebuild, decide one by one:

• you do not need it anymore: epkg remove <package>
• you want to keep it as it is: do nothing, the warning stays until it is removed
• it moved to a new name or version: install that one, then epkg remove the old one

Run epkg update first, sometimes the package is only missing because your repositories are old.

If you ask for help on our channels, this is what we want to see:

epkg sysinfo

Package Administration

Argent comes with some Gentoo sets that you need to remove if you want KDE removed.

Normally KDE Plasma can't be removed from Argent installation by a normal user - and this is the right way, it's like removing Windows 11 or MacOS UI.

But in order to remove this protection, you have to have some Gentoo knowledge, and understanding what you are doing.

So, basically you will have:

emerge --deselect plasma-workspace plasma-tools

Then, you can remove Plasma, and install something else.

If you are a developer, and want to start developing things with easy maintenance

You have to switch on development mode using avasile --help like this:

avasile --devmode

It's not a big issue, this will let you compile some things that you do not have, and versions that our precompiled repository do not have yet.

Normally a linux advanced user won't feel any difference between the normal user mode and devmode.

But essentially, the devmode will start installing build dependencies, and those dependencies are only used to compile or build programs.

In devmode you are allowed to change USE flags and keywords. Don't edit the Argent files in /etc/portage, create your own files next to them instead, like /etc/portage/package.use/100-my.package.use.

In user mode (avasile --usermode) you must not touch /etc/portage at all.

To sync everything for development

epkg update is enough for normal use. When you compile, you want every repository you have (including your own overlays) synced with emerge --sync, plus the Argent portage configuration:

epkg devsync

autocompile, autorecompile, recompile-depend, autorecompile-depend, recompileallpkg and autobuildpkgonly accept --update as the first argument, and in their case it runs epkg devsync first, not epkg update:

epkg autocompile --update <package>

If you need the full git history of the portage tree, the argent-ws overlay and the Argent portage configuration (for git log, git bisect, ...):

epkg force-sync

In this mode you can start using epkg to compile things, like this:

epkg compile <package>

epkg autocompile <package>

or

epkg recompile <package> or epkg re <package>

epkg autorecompile <package> or epkg are <package>

Both of them compile the package and install it. The difference: compile adds the package to your world file, like a normal install, while recompile is a one shot, it rebuilds what you already have and does not add it to your world file.

Compilation management

If you want to recompile every package that's based on a given package:

epkg recompile-depend <package>

No confirmation:

epkg autorecompile-depend <package>

It takes the exact installed version of each dependent package. If that ebuild is gone from the repositories, it uses a newer revision of the same version, and if there is none, it skips the package and tells you why. It doesn't stop at the first failed package, it continues with the rest.

Options:

--exclude <package> leaves a package out, you can repeat it, and it also takes slot atoms like dev-lang/python:3.12

--strict refuses to start if any package has to be skipped

--update (first argument only) runs epkg devsync first

epkg recompile-depend --update dev-libs/openssl --exclude sys-libs/glibc

Only one recompile-depend can run at a time.

If you changed USE flags and want to rebuild only what is affected:

epkg src-newuse <package>

To recompile the whole system (this is refused in user mode):

epkg recompileallpkg

No confirmation (it also runs epkg devsync and epkg cleanoutdated first):

epkg autorecompileallpkg

Post kernel recompilation

If you are on development mode, after the reinstallation and upgrading of all kernels, you must use:

epkg module-rebuild

Or automated:

epkg automodule-rebuild

If you get "preserved-rebuilds" warning

In order to compile the preserved-rebuild dependencies (that failed to compile for you):

epkg compile-preserved

No confirmation:

epkg autocompile-preserved

Compile-preserved knows what packages it needs to recompile in order to relink properly, it's the base foundation of a stable OS, compared to other distros that don't really care what they link against when they upload packages.

Building your own binary packages

Your local binary packages are saved in PKGDIR, usually /var/cache/binpkgs. These commands are refused in user mode.

To build packages without installing them:

epkg buildpkgonly <package>

No confirmation:

epkg autobuildpkgonly <package>

To build packages and then install them from the binary you just built (the local package index is regenerated as well):

epkg buildinstall <package>

No confirmation:

epkg autobuildinstall <package>

To save packages you already have installed, together with your configuration files (for example apache with your own configs, for later use):

epkg backuppkg <package>

The packages are saved in PKGDIR. Saving them somewhere else, with PKGDIR='/location/' epkg backuppkg <package>, is not yet implemented: epkg ignores it and still uses the PKGDIR from your make.conf.

To save every installed package:

epkg backupallpkg

Keep that backup safe, it is your whole system.

To remove the outdated packages from PKGDIR and from the downloaded binary packages in /var/cache/binhost/:

epkg cleanoutdated

epkg clean and epkg autoclean already do this on their own, unless you set EPKG_BACKUP_PKG="1" (see Local binary packages when cleaning).

To remove everything from PKGDIR:

epkg cleanlocalpkg

cleanlocalpkg does not touch the downloaded binary packages in /var/cache/binhost/.

To remove every binary package, the ones in /var/cache/binpkgs and all the downloaded ones in /var/cache/binhost/:

epkg wipe

No confirmation:

epkg awipe

It shows how much space each directory takes before removing anything, and it refuses to run while emerge or qmerge is working. At the end it rebuilds the empty local package index. The remote binhost indexes are downloaded again on their own by the next install or upgrade that uses binary packages. Everything you need later is downloaded again from the Argent binhost, but packages you built or backed up yourself are gone for good, epkg backuppkg included: copy them out of /var/cache/binpkgs first if you want to keep them.

If a directory is mounted read only, all of these commands skip it and tell you so.

Downloading only

To download the sources of a package (for patching, or to build later without network), usually in /var/cache/distfiles:

epkg fetchsourcepkg <package>

To download only the binary package from the Argent binhost, without installing it:

epkg fetchbinpkg <package>

Package configuration

Some packages need a configuration step after install (databases for example), the ebuild says so at the end of the install:

epkg configure <package> or epkg cfg <package>

Collision protection

When two packages want to install the same file, portage stops. If you know which package is right, you can turn the protection off for one run:

epkg install-no-collision <package>

No confirmation:

epkg autoinstall-no-collision <package>

Or for a whole system upgrade:

epkg upgrade-nocol

No confirmation:

epkg autoupgrade-nocol

Use them only when you know which package owns the file, otherwise you overwrite files from another package without any warning.

Binary packages only (experimental)

This is experimental. It works, but it is new, so keep using the commands from above for your daily work, and use these only if you want to test them and report what breaks.

These commands work only with precompiled packages from the Argent binhost, using qmerge (from our portage-utils). Nothing gets compiled here: if there is no binary package for what you ask, it refuses.

Most of them pass any extra option to qmerge, see qmerge --help.

To refresh the binhost index

epkg ibin-update or epkg iup

This runs epkg update first (epkg iup --clean runs epkg update --clean), then refreshes the binhost package index. It can take a while if you have many packages in /var/cache/binpkgs or /var/cache/binhost/.

If you give it packages, it only downloads them and their dependencies, without installing them:

epkg iup <package>

To install

epkg install-bin-pkg <package> or epkg ibin <package> or epkg ib <package>

No confirmation:

epkg autoinstall-bin-pkg <package> or epkg aibin <package> or epkg aib <package>

To see what would be installed, without touching the system:

epkg ibin-pretend <package> or epkg ip <package>

To upgrade

epkg ibin-upgrade or epkg iug

No confirmation:

epkg autoibin-upgrade or epkg aiug

Same as with epkg upgrade: run etc-update after it and accept the configuration changes that come from Argent.

To search

epkg ibin-search <package> or epkg is <package>

The name can be a regex. This one works as a normal user.

To remove

epkg ibin-remove <package> or epkg ir <package>

Like epkg remove, the package is removed only if nothing else needs it.

To remove everything that is no longer needed by your world set:

epkg ibin-clean or epkg ic

The same thing, with more output:

epkg iremove-orphans

No confirmation:

epkg airemove-orphans

To see how a package was built

epkg ibin-info <package>

It shows how the installed package was compiled: USE flags, build environment, what it links against. For a package on the binhost, not the installed one, use <package>@<repo>.

To see which binhost repositories you use, in priority order:

epkg ibin-repos

Both of them work as a normal user.

TLDR

TLDR to fully upgrade everything oneshot: epkg update && epkg upgrade

TLDR to skip those that are not compiled: epkg update && epkg upgrade --keep-going y

TLDR to to compile everything with build deps included: epkg update && epkg upgrade-full && epkg module-rebuild

TLDR to to compile everything with build deps included, skip those that do not compile and upgrade-compile everything in the dependency chain possible:

epkg update && epkg upgrade-full --complete-graph y --keep-going y && epkg module-rebuild