If a bashrc file is located at /etc/portage/bashrc then it will be sourced before an ebuild is executed.

A phase hook function name begins with a pre_ or post_ prefix to indicate that it will be called before or after one of the ebuild phases. The prefix is followed by the name of the ebuild function that the hook will be associated with. For example, a hook named pre_src_compile will be called before src_compile, and a hook named post_src_compile will be called after src_compile.

In order to significantly reduce the resources consumed by the modeling process, the dependencies of installed packages may be neglected.

If a more complete dependency calculation is desired, there is a --complete-graph option which will ensure that the dependencies of installed packages are properly considered.

In terms of boolean logic, a dependency expression can be expressed in disjunctive normal form (DNF), which is a disjunction of conjunctive clauses. Each conjunctive clause represents one possible alternative combination of dependency atoms capable of satisfying the dependency expression.

When there are multiple combinations to choose from, a look-ahead mechanism will choose an optimal combination to satisfy constraints and minimize cost. The following package states influence the cost calculation for a given combination:

In cost calculations, virtual packages by themselves are considered to cost nothing since they do not directly install anything. It is the dependencies of a virtual package that contribute to it's cost.

All tasks are executed in an order such that a task's dependencies are satisfied when it is executed. Dependency relationships between tasks form a directed graph.

Sometimes a package installation order exists such that it is possible to avoid having two conflicting packages installed simultaneously. If a currently installed package conflicts with a new package that is planned to be installed, it may be possible to solve the conflict by replacing the installed package with a different package that occupies the same slot.

In order to avoid a conflict, a package may need to be uninstalled rather than replaced. The following constraints protect inappropriate packages from being chosen for automatic uninstallation:

In order to ensure that package files remain installed in a usable state whenever possible, uninstallation operations are not executed until after all associated conflicting packages have been installed. When file collisions occur between conflicting packages, the contents entries for those files are removed from the packages that are scheduled for uninstallation. This prevents uninstallation operations from removing overlapping files that have been claimed by conflicting packages.

TODO: Automatically solve circular dependencies by temporarily disabling conditional dependencies and then rebuilding packages with the conditional dependencies enabled.

The algorithm used to choose packages that will execute concurrently with other packages is as conservative as possible in the sense that a given package will not be executed if the subgraph composed of its direct and indirect dependencies contains any scheduled merges. By ensuring that the subgraph of deep dependencies is fully up to date in this way, potential problems are avoided which could be triggered by other build orders that are less optimal.

    QA Notice: The following files contain insecure RUNPATHs
   

Some of the ELFs that would be installed on the system have insecure dynamic RUNPATH tags. RUNPATH tags are a hardcoded list of filesystem paths that will be searched at runtime when the ELF is executed. If the ELF has a world accessible directory hardcoded in it, then a malicious person can inject code at runtime by adding their own libraries to the directory.

Here are some of the common problems and their solutions.

    QA Notice: The following files contain runtime text relocations
   

Please see the Gentoo Hardened PIC Fix Guide.

    QA Notice: The following files contain executable stacks
   

Please see the Gentoo Hardened GNU Stack Guide.

    QA Notice: The following shared libraries lack a SONAME
   

A shared library that you would link against lacks an ELF SONAME tag. With simpler libraries, this can be acceptable, but with any sort of ABI sane setup, you need the SONAME tag. This tag is how the system linker tells the loader what libraries a program needs at runtime. With a missing SONAME, the linker needs to guess and with many cases, this guess will not work for long.

To fix this issue, make sure the shared library is linked with the proper -Wl,-soname,... flag. You will need to replace the ... part with the actual ABI name. For example, if the library is named libfoo.so.1.2.3, you will probably want to specify -Wl,-soname,libfoo.so.1.

Note that this warning only applies to shared libraries that you would link against. It certainly does not apply to plugins that you would dynamically load. However, plugins should not exist in the main library directory, but rather an application specific subdirectory in the library directory. In other words, it should be /usr/lib/app/plugin.so rather than /usr/lib/plugin.so.

    QA Notice: The following shared libraries lack NEEDED entries
   

This warning comes up when a library does not actually seem to need any other libraries in order to run. Rarely is this true as almost every library will need at least the system C library.

Once you've determined that the library is indeed being generated incorrectly, you will need to dig into the build system to make sure that it pulls in the libraries it needs. Often times, this is because the build system invokes the system linker (ld) directly instead of the system compiler driver (gcc).

    QA Notice: Found an absolute symlink in a library directory
   

If you want to use symlinks in library directories, please use either a relative symlink or a linker script. This can cause problems when working with cross-compiler systems or when accessing systems in a different ROOT directory.

If you have a library installed into /lib/ and you want to have it accessible in /usr/lib/, then you should generate a linker script so that the system toolchain can handle it properly. Please see the linker script section for more information.

    QA Notice: Missing gen_usr_ldscript
   

If you have a shared library in /lib/ and a static library in /usr/lib/, but no linker script in /usr/lib/, then the toolchain will choose the incorrect version when linking. The system linker will find the static library first and not bother searching for a dynamic version. To overcome this, you need to use the gen_usr_ldscript function found in the toolchain-funcs.eclass. Refer to the man page for information on how to use it. See this bug report for some history on this issue.

    QA Notice: Excessive files found in the / partition
   

You should not store files that are not critical to boot and recovery in the root filesystem. This means that static libraries and libtool scripts do not belong in the /lib/ directory. Fix your ebuild so it does not install there.

    QA Notice: ... appears to contain PORTAGE_TMPDIR paths
   

Older versions of libtool would incorrectly record the build and/or install directory in the libtool script (*.la). This would lead to problems when building other things against your package as libtool would be confused by the old paths.

You may be able to cheat and use the elibtoolize function in the libtool.eclass. However, if that does not help, you will probably need to regenerate all of the autotool files.

    QA Notice: Package has poor programming practices which may compile
               fine but exhibit random runtime failures.
    ...: warning: dereferencing type-punned pointer will break strict-aliasing rules
   

This warning crops up when code starts casting distinct pointer types and then dereferencing them. Generally, this is a violation of aliasing rules which are part of the C standard. Historically, these warnings did not show up as the optimization was not turned on by default. With gcc-4.1.x and newer though, the -O2 optimization level enables strict aliasing support. For information, please review these links: NetBSD Explanation, Gentoo Dev Thread, GCC Docs

To fix this issue, use the methods proposed in the links mentioned earlier. If you're unable to do so, then a work around would be to append the gcc -fno-strict-aliasing flag to CFLAGS in the ebuild.

    QA Notice: Package has poor programming practices which may compile
               fine but exhibit random runtime failures.
    ...: warning: implicit declaration of function ...
    ...: warning: incompatible implicit declaration of built-in function ...
   

Your code is calling functions which lack prototypes. In C++, this would have been a build failure, but C is lazy so you just get a warning. This can be a problem as gcc has to guess at what sort of arguments a function takes based upon how it was called and often times, this is not the same as what the function actually takes. The function return type is also unknown so it's just assumed to be an integer (which is often times wrong). This can get to be a problem when the size of the types guessed do not actually match the size of the types the function expects. Generally, this corresponds directly to proper coding practices (and the lack thereof). Also, by including proper prototypes, the compiler often helps by checking types used, proper number of arguments passed, etc...

To fix this, just include the proper header files for the functions in question. If the function is a package-specific one, then you may have to create a header/function prototype for it.

    QA Notice: Package has poor programming practices which may compile
               fine but exhibit random runtime failures.
    ...: warning: is used uninitialized in this function
   

This means code uses a variable without actually setting it first. In other words, the code is basically using random garbage.

The fix here is simple: make sure variables are initialized properly before using them.

    QA Notice: Package has poor programming practices which may compile
               fine but exhibit random runtime failures.
    ...: warning: comparisons like X<=Y<=Z do not have their mathematical meaning
   

This warning crops up either when the programmer expected the expression to work or they just forgot to use sufficient parentheses. For example, the following code snippets are wrong (we won't get into the technical argument of this being valid C code; just change the code to not be ambiguous).

    if (x <= y <= z)
      ...;
    if (a < b <= c)
      ...;
   

To fix this, read the code to figure out what exactly the programmer meant.

    QA Notice: Package has poor programming practices which may compile
               fine but exhibit random runtime failures.
    ...: warning: null argument where non-null required
   

Many functions take pointers as arguments and require that the pointer never be NULL. To this end, you can declare function prototypes that instruct the compiler to do simple checks to make sure people do not incorrectly call the function with NULL values. This warning pops up when someone calls a function and they use NULL when they should not. Depending on the library, the function may actually crash (they told you not to use NULL after-all, so it's your fault :P).

You will need to read the code and fix it so that it does not incorrectly call the relevant functions with NULL values.

    QA Notice: Package has poor programming practices which may compile
               but will almost certainly crash on 64bit architectures.
   

A large portion of code in the open source world is developed on the 32bit x86 architecture. Unfortunately, this has led to many pieces of code not handling pointer types properly. When compiled and run on a 64bit architecture, the code in question will probably crash horribly. Some common examples are assuming that an integer type is large enough to hold pointers. This is true on 32bit architectures (an integer can hold 32bits and a pointer is 32bits big), but not true on 64bit architectures (an integer still holds just 32bits, but a pointer is 64bits big).

Since this issue can manifest itself in many ways (as there are many ways to improperly truncate a pointer), you will need to read the source code starting with the displayed warning. Make sure types are declared, used, and passed properly. Make sure that all function prototypes are found (see the Implicit Declarations section for more information). So on and so forth.