Updated 08/12/2021. If there’s anything wrong, inacurate or if you just want to tell me to add things, email me at bronze@kitsunemimi.club (preferably with gpg, don’t be a fag)
Refresher list for commonly used commands.
Search engine for gentoo packages in various overlays.
Gentoo is a source based Linux distribution. Unlike the more commonly seen distros (Ubuntu, Fedora etc.) it does not download binaries but instead downloads their source and compiles it. This allows for a level of customization that goes beyond distros like Arch (which is already known for how flexible it is) since Gentoo is basically a meta linux distribution. This might put off a lot of people, since it requires a lot of patience not only to learn and understand how Linux (the kernel and the programs running on top of it) come together but also the fact that, by default, compilling a package will take a lot more time than just downloading an executable. An easy way to think of all of this is that binary-based distros are akin to ordering takeout, while source based distros would be more like asking your maid to get some groceries and cook for you. Sure, takeout is quick, easy and offers plenty of choices but if you’re concerned about things like ingredient quality or how fresh the food is, it might be better to just make your own food.
Gentoo installs are almost like Arch installs, except the only thing really holding your hand is the Gentoo Handbook. This guide is meant to provide supplemental information (mostly from what I’ve learned over the years) so that its easier for someone to understand the whole process. Here’s a short bullet note summary:
Of course, this is a very simplified list of steps, but it also serves to show how simple the actual concepts are. Remember, you shouldn’t be copy and pasting commands into your terminal but rather thinking about how to check these steps off on your list. Meaning, you’re very flexible in the way you go about the install process.
Also, notice how I mentioned “linux livecd” in the first step rather than “the gentoo livecd”. My option of the Gentoo Livecd is kinda soured from back when it sucked. The minimal installation environment just drops you in a shell (like Arch) and leaves you to your own devices. However you don’t actually have to use the gentoo livecd. Because of how simple these steps are, you can work off of anything that boots you into a working environment. Just boot with an Ubuntu, Mint or Manjaro livecd and make sure everything on your computer works properly on a “normie-tier” linux distro. I use tools like GParted or KDE’s partition manager to visualize what I’m actually doing to the hard drive. That and I can have a web browser with the gentoo handbook right next to the terminal window I’m working out of.
Also theres nothing funnier than using another distro to install Gentoo you’re literally cucking that distro LMFAO
A big and “scary” part of the gentoo install is building the linux kernel. Most people try to do the whole thing manually, mess it up and rage quit out of frustration. I know because I was one of those people. After I re-visited gentoo I wanted to figure out an easier way to do all of this. What I’ve found is that you have several options regarding the kernel, I’ll try and list them all here and keep a short guide of how to install them:
Its $current_year, so of course gentoo offers a precompiled kernel. If you don’t want to build a kernel, install this and you’re good to go.
emerge sys-kernel/gentoo-kernel-bin
EDIT: Seriously this is brand new. See this blog post published 9/15/20. Linux kernel installation (compiled from source or the binary package above) all through portage. I haven’t tried these packages so I don’t know how well they work but you could try them out and see how they work.
Install and run genkernel and let it do the heavy lifting.
emerge sys-kernel/genkernel
Genkernel article on gentoo wiki
This is my favorite way of doing this. What I do is I base it off of an existing, working kernel config. You can do this by checking which modules the kernel has loaded and enabling them, either automatically when you make the config or manually inside menuconfig. This is the reason why I choose to use non-gentoo install media. Normie distros are usually able to detect things like laptop cameras or include support for things like sound cards so we’re just going to mooch off of them for a second. This method is essentially a semi-automatic way of making a stripped down kernel tailored to your computer. Now would be a good time to turn on your webcam or bluetooth in order to make sure that the kernel actually loads those modules and that the hardware works well under linux.
emerge sys-kernel/gentoo-sources
There are also other kernel sources you can download. Take a look at the sys-kernel category to see more. I’m using gentoo-sources because its the default for gentoo + includes all the distro specific shit.
Have eselect set the symlink for your linux kernel folder (that way all your packages know where to look for the kernel youre using)
eselect kernel list
eselect kernel set 1Go into your kernel directory and tell it to copy the config
cd /usr/src/linux
make localmodconfigIf that went off without a hitch then youre all set. You should have a kernel configuration that is stripped down. Feel free to run make menuconfig in order to look at / enable any new modules. For the love of god enable the /proc/config.gz module if it wasn’t enabled already. It will make your life so much easier in the future. Trust me.
If you got an error above while trying to run make localmodconfig then please try this
lsmod > lsmod.txt
make LSMOD="lsmod.txt" localmodconfigThe first command pipes the output of lsmod (LiSt MODules) to a text file. The second command just make sure to use that file as our module list for the kernel. Sometimes, the reason this happens is because some distros don’t provide a /proc/config.gz making the command not work correctly.
Compile and install Linux kernel
make LD=ld.bfd -j4 # j{n+1} where n = cpu cores
make modules_install
make install
genkernel --install initramfs
grub-mkconfig -o /boot/grub/grub.cfgYou should be all set with a kernel that boots and works with your devices. The genkernel command makes and installs an initramfs into /boot as well.
Upgrading the kernel
#download new source
eselect kernel list
eselect kernel set 2 #or whichever number is the new one
zcat /proc/config.gz > .config
#if this doesnt work try copying config from boot
make syncconfigThen follow the steps for compilling and installing the kernel.
Probably the most important file. Its where all your compiler flags and global use flags go into. Here is an example from one of my laptops:
# These settings were set by the catalyst build script that automatically
# built this stage.
# Please consult /usr/share/portage/config/make.conf.example for a more
# detailed example.
COMMON_FLAGS="-O2 -pipe -march=native"
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"
FCFLAGS="${COMMON_FLAGS}"
FFLAGS="${COMMON_FLAGS}"
# NOTE: This stage was built with the bindist Use flag enabled
PORTDIR="/var/db/repos/gentoo"
DISTDIR="/var/cache/distfiles"
PKGDIR="/var/cache/binpkgs"
# FLAGS
ABI_X86="64 32"
CPU_FLAGS_X86="aes avx f16c mmx mmxext pclmul popcnt sse sse2 sse3 sse4_1 sse4_2 ssse3"
USE="-bindist -systemd -rust -consolekit elogind gtk -gnome -gnome-keyring X libglvnd acpi qt5 kde grub alsa pulseaudio eudev dbus policykit udisks bluetooth sddm networkmanager llvm threads ffmpeg kdesu"
VIDEO_CARDS="intel i965"
# This sets the language of build output to English.
# Please keep this setting intact when reporting bugs.
LC_MESSAGES=C
MAKEOPTS="-j5"One of the most important variables of note here is the COMMON_FLAGS variable. This one is new (from late 2019 I think?) and serves as a way to simplify C(XX)FLAGS. These are the compiler options set when you’re compiling software. If you’ve ever compiled something manually then this should be familliar.
-O2 is our level of optimization. I personally use O2 and most distros also use O2 when they compile their software. I personally wouldn’t recommend setting it to O3 unless its a per package option (see the portage/env part to know how).
-march=native tells the compiler to detect what CPU we are using and optimize for that. We obviously want this. If you are compilling on your own machine only (ie. without DistCC) you can get away with using this just fine. If you want to use DistCC, you can’t use -march=native as it will fuck up your program badly. Read here why you shouldn’t do this. Essentially. if you run -march=native with DistCC it will compile your programs wrong if you’re using different CPUs in your compilation pool. Here is a package that can easily break down march=native into the flags gcc detects: app-misc/resolve-march-native
You should use the “real” flags if you’re planning on using your computer with DistCC.
Read more on what you can do here. There is no need to overtune these variables. Don’t be one of the people that would get featured in this.
These are for all the extra instruction sets your CPU carries, think SSE, AVX etc. These used to be part of the USE flags but now have their own variable and section. There is also a package that helps you figure out what they are for your computer: app-portage/cpuid2cpuflags
If you’re on other architectures then you’re not going to deal with CPU_FLAGS_X86 but instead something like CPU_FLAGS_PPC or CPU_FLAGS_ARM depending on what arch youre using. Same difference.
All packages that can be compiled with portage have compile time options that are abstracted into USE flags. These tell Portage what features should and shouldn’t be compiled into your packages. In the example above I choose not to have my packages compile with systemd with the -systemd option, as I don’t use systemd. I also enable qt5 and kde since I use KDE and I would like my software to build with support for that if those use flags are available.
The -bindist flag is set for simplicity regarding openssl builds (and some other packages too). You’re not allowed to “share” your built binary of openssl if it contains certain algorithms. Not like I’ll ever share my binaries.
This is how many cores your computer can use to compile things in parallel. The usual rule is the number of cores +1. In my example, I’ve got a quad core CPU so I use -j5 (since 4+1).
ABI_X86 : Determines if you want to compile 64 and 32 bit support into your applications. I have it set for both. Feel free to not even have this in your make.conf
VIDEO_CARDS : Kind of like CPU_FLAGS_X86 but for video cards. Read this to figure out what is available. Set it to whatever video cards you have.
There’s more listed in this article.
This is where all the portage configuration lives.
package.accept_keywords
package.use
package.license
package.mask
package.unmaskThese can either be a file or a folder. I find making them into folders to be much better for organizing stuff. You can put files inside those folders organized with any sort of category. For example, a “free” and “non-free” file under package.license or a KDE file for all KDE specific software under package.accept_keywords and package.use. Here is an example of what I have in my package.accept_keywords/kde
# CUSTOM KDE ALL
kde-plasma/* ~amd64
kde-apps/* ~amd64
kde-misc/* ~amd64
kde-frameworks/* ~amd64
dev-qt/* ~amd64
#this wasnt under kde-apps
app-office/kmymoney ~amd64
dev-util/kdevelop ~amd64
dev-util/kdevelop-python ~amd64
www-client/falkon ~amd64
app-portage/kuroo ~amd64
app-cdr/dolphin-plugins-mountiso ~amd64The ~amd64 denotes to portage what packages can have their testing versions installed. Testing versions are more up to date but haven’t passed all the bug testing / vetting the gentoo team does. By default, all stable packages are enabled but it doesn’t hurt to enable testing packages. In the above file I’ve enabled testing for all KDE packages and all Qt packages and anything else related to KDE I didn’t want a stable version for.
Beware that if you do something like this:
*/* ~amd64
You will probably break your install somehow. There’s a reason why these packages are in “testing”. It’s better to just enable them selectively or by category if youre feeling lucky.
Packages pulled straight from git and compiled will be version 9999, and will need ** instead of ~amd64 to enable them.
The main Gentoo repository is located under /var/db/repos/gentoo (this is a recent change, on older systems it would’ve been /usr/portage) This is where all your ebuild files are kept.
If the Gentoo repo is missing something, it might be available in another repository. There are two ways of adding a custom repository to your Gentoo system.
This is a great website if you want to search for a package in every repo:
Lets say were creating a local repo simply named “local”.
Create this file /etc/portage/repos.conf/local.conf and add this:
[local]
location = /var/db/repos/localWhere whats in the brackets is the name of your repo, and the location variable is set to where its stored.
Create the folder the repo is going to go under:
mkdir /var/db/repos/local
Create two folders in there, metadata and profiles (all lowercase). Create a file under metadata called layout.conf and add this:
masters = gentoo
auto-sync = falseCreate a file under profiles called repo_name and add the name of the repo to it:
echo local > /var/db/repos/local/profiles/repo_name
Add any new ebuild to the overlay. It follows the same structure as the main gentoo repo so category/packagename with the ebuild inside. We also need a Manifest file inside the ebuild’s folder. This file stores all hashes of files associated with the ebuild. Create this file by issuing the command below:
ebuild {ebuildfile} digest Where ebuild file is whatever .ebuild file needs one.
Keep in mind that any change to the source code of the ebuild will require an update to the manifest file.
There you go! Your own custom overlay! If you want to share it, it’s just a matter of hosting it online with github. If you want to add support for layman, you need to create an overlay.xml file. Here’s an example overlay.xml from my own personally managed overlay:
<?xml version="1.0" ?>
<repositories version="1.0">
<repo priority="50" quality="experimental" status="unofficial">
<name>bronze-overlay</name>
<description>bronze's misc gentoo overlay</description>
<homepage>https://kitsunemimi.club/git/bronze/bronze-overlay</homepage>
<owner>
<email>bronze@kitsunemimi.club</email>
</owner>
<source type="git">https://kitsunemimi.club/git/bronze/bronze-overlay.git</source>
</repo>
</repositories>And here’s the command to add this overlay with layman:
layman -o https://kitsunemimi.club/git/bronze/bronze-overlay/raw/branch/master/overlay.xml -f -a bronze-overlay
Here’s the command to add my overlay using eselect-repository (haven’t tested this):
eselect repository add bronze-overlay git https://kitsunemimi.club/git/bronze/bronze-overlay.git
I personally like flatpak and use it as a supplement to Portage from time to time. However please keep in mind that you should always be using the distro’s package manager first and foremost (this goes for any distro, not just Gentoo). Don’t go adding flatpak into Gentoo just because of this guide. Please read into Flatkill and put some thought into whether or not you should add a completely new package manager on top of your existing one.
Emerge flatpak using:
emerge -a sys-apps/flatpak
Once that’s done, run this command to add the Flathub repository to flatpak:
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
The command above doesn’t need to be run as root. In fact, you should run flatpak as yourself 99% of the time.
You should also get a hold of Flatseal to manage flatpak program’s permissions.
If you’re using flatpak for electronshit like Riot Element or Briscord please keep track of app-crypt/p11-kit. Those apps won’t work depending on that package’s version, and most likely you’ll need the testing version enabled. See this for more info.