Add a section on compiling and linking in the programming guide.

---

 cur-root/doc/guide.lyx |   93 +++++++++++++++++++++++++++++++++++++++++++++++++
 cur-root/doc/guide.txt |   41 ++++++++++++++++++++-
 2 files changed, 132 insertions(+), 2 deletions(-)

diff -puN doc/guide.lyx~linking_doc doc/guide.lyx
--- cur/doc/guide.lyx~linking_doc	2004-09-19 01:32:39.735832824 -0300
+++ cur-root/doc/guide.lyx	2004-09-19 01:32:39.739832216 -0300
@@ -657,6 +657,99 @@ fwrite()
  Let me know if you need them.
 \layout Section
 
+Compiling and linking
+\layout Standard
+
+When you want to use your library, besides including the 
+\emph on 
+
+\begin_inset Quotes eld
+\end_inset 
+
+libjio.h
+\begin_inset Quotes erd
+\end_inset 
+
+
+\emph default 
+ header, you have to make sure your application uses the Large File Support
+ (
+\begin_inset Quotes eld
+\end_inset 
+
+LFS
+\begin_inset Quotes erd
+\end_inset 
+
+ from now on), to be able to handle large files properly.
+ This means that you will have to pass some special standard flags to the
+ compiler, so your C library uses the same data types as the library.
+ For instance, on 32-bit platforms (like x86), when using LFS, offsets are
+ usually 64 bits, as opposed to the usual 32.
+\layout Standard
+
+The library is always built with LFS; however, link it against an application
+ without LFS support could lead to serious problems because this kind of
+ size differences and ABI compatibility.
+\layout Standard
+
+The Single Unix Specification standard proposes a simple and practical way
+ to get the flags you need to pass your C compiler to tell you want to compile
+ your application with LFS: use a program called 
+\emph on 
+
+\begin_inset Quotes eld
+\end_inset 
+
+getconf
+\begin_inset Quotes erd
+\end_inset 
+
+
+\emph default 
+ which should be called like 
+\emph on 
+
+\begin_inset Quotes eld
+\end_inset 
+
+getconf LFS_CFLAGS
+\begin_inset Quotes erd
+\end_inset 
+
+
+\emph default 
+, and it outputs the appropiate parameters.
+ Sadly, not all platforms implement it, so it's also wise to pass 
+\emph on 
+
+\begin_inset Quotes eld
+\end_inset 
+
+-D_FILE_OFFSET_BITS=64
+\begin_inset Quotes erd
+\end_inset 
+
+
+\emph default 
+ just in case.
+\layout Standard
+
+In the end, the command line would be something like:
+\layout LyX-Code
+
+gcc `getconf LFS_CFLAGS` -D_FILE_OFFSET_BITS=64 
+\backslash 
+
+\layout LyX-Code
+
+        app.c -ljio -lpthread -o app
+\layout Standard
+
+If you want more detailed information or examples, you can check out how
+ the library and sample applications get built.
+\layout Section
+
 Where to go from here
 \layout Standard
 
diff -puN doc/guide.txt~linking_doc doc/guide.txt
--- cur/doc/guide.txt~linking_doc	2004-09-19 01:32:39.736832672 -0300
+++ cur-root/doc/guide.txt	2004-09-19 01:32:39.740832064 -0300
@@ -18,7 +18,8 @@ Table of Contents
 7 Other APIs
     7.1 UNIX API
     7.2 ANSI C API
-8 Where to go from here
+8 Compiling and linking
+9 Where to go from here
 
 
 
@@ -329,7 +330,43 @@ They're still in development and has not
 carefully, so I won't spend time documenting them. Let 
 me know if you need them.
 
-8 Where to go from here
+8 Compiling and linking
+
+When you want to use your library, besides including 
+the "libjio.h" header, you have to make sure your 
+application uses the Large File Support ("LFS" from now 
+on), to be able to handle large files properly. This 
+means that you will have to pass some special standard 
+flags to the compiler, so your C library uses the same 
+data types as the library. For instance, on 32-bit 
+platforms (like x86), when using LFS, offsets are 
+usually 64 bits, as opposed to the usual 32.
+
+The library is always built with LFS; however, link it 
+against an application without LFS support could lead 
+to serious problems because this kind of size 
+differences and ABI compatibility.
+
+The Single Unix Specification standard proposes a 
+simple and practical way to get the flags you need to 
+pass your C compiler to tell you want to compile your 
+application with LFS: use a program called "getconf" 
+which should be called like "getconf LFS_CFLAGS", and it 
+outputs the appropiate parameters. Sadly, not all 
+platforms implement it, so it's also wise to pass "
+-D_FILE_OFFSET_BITS=64" just in case.
+
+In the end, the command line would be something like:
+
+gcc `getconf LFS_CFLAGS` -D_FILE_OFFSET_BITS=64 \
+
+        app.c -ljio -lpthread -o app
+
+If you want more detailed information or examples, you 
+can check out how the library and sample applications 
+get built.
+
+9 Where to go from here
 
 If you're still interested in learning more, you can 
 find some small and clean samples are in the "samples" 
_