source: chapter01/askforhelp.xml@ ec0a37e6

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>
<sect1 id="prepare-askforhelp">
<title>Help</title>
<?dbhtml filename="askforhelp.html"?>

<para>If you encounter an issue or have a question while working
through this book, check our FAQs page at <ulink url="&faq-root;"/>.
Often times questions are already answered there. If your question is
not answered on this page, try to find the source of the problem. The
following hint will give you some guidance for troubleshooting: <ulink
url="&hints-root;errors.txt"/>.</para>

<para>We also have a wonderful LFS community that is willing to offer
assistance through IRC and the mailing lists (see the <xref
linkend="ch-scatter-administrativa"/> section of this book). In order
to assist them with diagnosing and solving the problem, please include
all relevant information in your request for help.</para>

<sect2>
<title>Things to mention</title>
 
<para>Apart from a brief explanation of the problem being experience,
the essential things to include in your request for help are:</para>

<itemizedlist>
<listitem><para>The version of the book you are using (in this case
&version;)</para></listitem>
<listitem><para>The host distribution and version you are using to
create LFS</para></listitem>
<listitem><para>The package or section giving you problems</para></listitem>
<listitem><para>The exact error message or symptom you are receiving</para></listitem>
<listitem><para>Note whether you have deviated from the book at all </para></listitem>
</itemizedlist>

<note><para>Deviating from this book does <emphasis>not</emphasis>
mean that we won't help you. After all, LFS is about your personal
preference. Being upfront any changes to the established procedure
help us evaluate and determine possible causes of your
problem.</para></note>
</sect2>

<sect2>
<title>Configure problems</title>

<para>If something goes wrong during the stage where the configure
script is run, review the <filename>config.log</filename> file. This
file may contain errors encountered during configure which were not
printed to the screen. Include those relevant lines if you need to ask
for help.</para>
</sect2>

<sect2>
<title>Compile problems</title>

<para>The both screen output and the contents of various files are
useful in determining the cause of compile issues. The screen output
from both the ./configure script and the make run can be helpful. It
is not necessary to include the entire output, but do include enough
of the relevant information. Below is an example of the type of
information to include from the screen output from make:</para>

<screen><computeroutput>gcc -DALIASPATH=\"/mnt/lfs/usr/share/locale:.\"
-DLOCALEDIR=\"/mnt/lfs/usr/share/locale\" -DLIBDIR=\"/mnt/lfs/usr/lib\"
-DINCLUDEDIR=\"/mnt/lfs/usr/include\" -DHAVE_CONFIG_H -I. -I.
-g -O2 -c getopt1.c
gcc -g -O2 -static -o make ar.o arscan.o commands.o dir.o expand.o file.o
function.o getopt.o implicit.o job.o main.o misc.o read.o remake.o rule.o
signame.o variable.o vpath.o default.o remote-stub.o version.o opt1.o
-lutil job.o: In function `load_too_high':
/lfs/tmp/make-3.79.1/job.c:1565: undefined reference to `getloadavg'
collect2: ld returned 1 exit status
make[2]: *** [make] Error 1
make[2]: Leaving directory `/lfs/tmp/make-3.79.1'
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory `/lfs/tmp/make-3.79.1'
make: *** [all-recursive-am] Error 2</computeroutput></screen>

<para>In this case, many people would just include the bottom
section:</para>

<screen><computeroutput>make [2]: *** [make] Error 1</computeroutput></screen>

<para>This is not enough information to properly diagnose the problem
because it only notes that something went wrong, not
<emphasis>what</emphasis> went wrong.  The entire section, as in the
example above, is what should be saved because it includes the command
that was executed and the associated error message(s).</para>

<para>An excellent article about asking for help on the Internet is
available online at <ulink
url="http://catb.org/~esr/faqs/smart-questions.html"/>.  Read and
follow the hints in this document to increase your changes of getting
the help you need.</para>
</sect2>

<sect2>
<title>Test suite problems</title>

<para>Many packages provide a test suite which, depending on the
importance of the package, should be run. Sometimes packages will
generate false or expected failures. If these errors are encountered,
check the LFS Wiki page at <ulink url="&wiki-root;"/> to see if we have
noted and investigated these issues. If these issues are noted and
addressed, there is no need to be concerned.</para>
</sect2>

</sect1>