From 4a0fd8c7bf04c0d4c1e356489487ff89afc7e2ea Mon Sep 17 00:00:00 2001 From: Zac Medico Date: Thu, 21 Jun 2007 07:13:05 +0000 Subject: [PATCH] - start documenting qa notices so antarus stops whining (trunk r5693) - forgot to document strict alias warnings (trunk r5733) - fix programlisting output to match the sections they are in (trunk r5734) svn path=/main/branches/2.1.2/; revision=6910 --- doc/Makefile | 11 ++ doc/custom.xsl | 0 doc/fragment/date | 0 doc/fragment/version | 1 + doc/portage.docbook | 32 ++++ doc/qa.docbook | 361 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 405 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/custom.xsl create mode 100644 doc/fragment/date create mode 100644 doc/fragment/version create mode 100644 doc/portage.docbook create mode 100644 doc/qa.docbook diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..c829639ca --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,11 @@ +all: xhtml xhtml-nochunks + +XMLTO_FLAGS_man = -x custom.xsl +man pdf txt xhtml xhtml-nochunks: + xmlto $@ $(XMLTO_FLAGS_$@) portage.docbook + +clean distclean: + rm -f *.1 *.html + +.PHONY: all clean distclean \ + man pdf txt xhtml xhtml-nochunks diff --git a/doc/custom.xsl b/doc/custom.xsl new file mode 100644 index 000000000..e69de29bb diff --git a/doc/fragment/date b/doc/fragment/date new file mode 100644 index 000000000..e69de29bb diff --git a/doc/fragment/version b/doc/fragment/version new file mode 100644 index 000000000..f2b80a3bd --- /dev/null +++ b/doc/fragment/version @@ -0,0 +1 @@ +svn-trunk diff --git a/doc/portage.docbook b/doc/portage.docbook new file mode 100644 index 000000000..1ca868722 --- /dev/null +++ b/doc/portage.docbook @@ -0,0 +1,32 @@ + + + + + + + +]> + + + + + Portage Documentation + + + + Mike + Frysinger + vapier@gentoo.org + + + + &version; + &date; + + +&qa; + + diff --git a/doc/qa.docbook b/doc/qa.docbook new file mode 100644 index 000000000..a8178d5b7 --- /dev/null +++ b/doc/qa.docbook @@ -0,0 +1,361 @@ + + QA Notices + + Here we'll go over each QA notice and what you (as a developer) can do to fix + the issue. If you're a user, you should of course go + file a bug. We'll only cover the + non-obvious notices here. + + + In pretty much all cases, you should try and get these issues resolved + upstream rather than simply fixing them in our ebuilds. + + + + Scanelf: Insecure RUNPATHs + + + QA Notice: The following files contain insecure RUNPATH's + + + + 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. + + + Libtool - old versions of libtool would use too many -rpath flags + Solution: Regenerate the autotool code + + + Perl - some versions of perl would use incorrect -rpath flags + Solution: upgrade system perl build modules + + + Crappy build system - the custom build system uses -rpath incorrectly + Solution: review the LDFLAGS in the build system and make them not suck + + + Crappy ebuild - the ebuild installs ELFs instead of using the package's build system + Solution: fix the crappy ebuild to use the package's build system + + + + + + + Scanelf: Runtime Text Relocations (TEXTRELS) + + + QA Notice: The following files contain runtime text relocations + + + + Please see the Gentoo Hardened PIC Fix Guide. + + + + + Scanelf: Executable Stack (EXECSTACK) + + + QA Notice: The following files contain executable stacks + + + + Please see the Gentoo Hardened GNU Stack Guide. + + + + + Scanelf: Missing Shared Object Name (SONAME) + + + 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 + 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 . + + + 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. + + + + + Scanelf: Missing Needed Entries + + + 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). + + + + + Absolute Symlink In Library Directory + + + 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. + + + + + Missing Linker Script + + + 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. + + + + + Excessive Files in / + + + 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. + + + + + Portage Tempdir In Libtool Scripts + + + 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. + + + + + Build Warning: Strict Aliasing + + + 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. + + + + + Build Warning: Implicit Declarations + + + 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. + + + + + Build Warning: Used Uninitialized + + + 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. + + + + + Build Warning: Invalid X<=Y<=Z Comparisons + + + 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. + + + + + Build Warning: Non-Null Required + + + 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. + + + + + Build Warning: Truncating Pointers + + + 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. + + + -- 2.26.2