* doc/sdccman.lyx: documented ar format libraries
[fw/sdcc] / doc / sdccman.lyx
index 801cffb5ee50c7bece94800a704a90dee2e0189d..9b11f7b8178f8ccde047104b4a31b47e7f0552fd 100644 (file)
@@ -7082,6 +7082,84 @@ name "-\\/-debug"
  is embedded in the library file itself.
  Library files created using sdcclib are used as described in the preceding
  sections.
  is embedded in the library file itself.
  Library files created using sdcclib are used as described in the preceding
  sections.
+\end_layout
+
+\begin_layout Subsection
+Using sdcclib to Create and Manage Libraries
+\begin_inset LatexCommand index
+name "ar"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Support for ar format libraries was introduced in sdcc 2.9.0.
+ Ar is a standard archive managing utility on unices (Linux, Mac OS X, several
+ unix flavors) so it is not included in the sdcc package.
+\series bold
+
+\newline
+
+\newline
+
+\series default
+For Windows platform you can find ar utility in GNU binutils package included
+ in several projects: Cygwin at 
+\begin_inset LatexCommand url
+target "http://www.cygwin.com/"
+
+\end_inset
+
+, MinGW at 
+\begin_inset LatexCommand url
+target "http://www.mingw.org/"
+
+\end_inset
+
+.
+\series bold
+
+\newline
+
+\newline
+
+\series default
+Both the GNU and BSD ar format variants are suppurated by asxxxx linkers.
+ Ar doesn't understand the asxxxx object file format, so there is a special
+ version of ranlib distributed with sdcc, called asranlib, which produces
+ the ar symbol lookup table.
+\series bold
+
+\newline
+
+\newline
+
+\series default
+To create a library containing asxxxx object files, you should use the following
+ sequence:
+\series bold
+
+\newline
+
+\end_layout
+
+\begin_layout Standard
+
+\family sans
+\series bold
+ar -Sq <library name>.lib <list of .rel files>
+\end_layout
+
+\begin_layout Standard
+
+\family sans
+\series bold
+asranlib <library name>.lib
+\end_layout
+
+\begin_layout Standard
 \begin_inset VSpace bigskip
 \end_inset
 
 \begin_inset VSpace bigskip
 \end_inset
 
@@ -21001,7 +21079,7 @@ name "printf()"
 printf_large.c
 \family default
  does not support float (except on ds390).
 printf_large.c
 \family default
  does not support float (except on ds390).
- To enable this recompile it with the option 
+ To enable this, recompile it with the option 
 \emph on
 -
 \begin_inset ERT
 \emph on
 -
 \begin_inset ERT
@@ -21049,6 +21127,13 @@ name "-\\/-model-large"
 
 \emph default
  for the mcs51 port, since this uses a lot of memory.
 
 \emph default
  for the mcs51 port, since this uses a lot of memory.
+ To enable float support for the pic16 targets, see 
+\begin_inset LatexCommand ref
+reference "sub:pic16Libraries"
+
+\end_inset
+
+.
 \end_layout
 
 \begin_layout Standard
 \end_layout
 
 \begin_layout Standard
@@ -27254,9 +27339,19 @@ Building the libraries
 Before using SDCC/pic16 there are some libraries that need to be compiled.
  This process is done automatically if gputils are found at SDCC's compile
  time.
 Before using SDCC/pic16 there are some libraries that need to be compiled.
  This process is done automatically if gputils are found at SDCC's compile
  time.
- Should you require to rebuild the pic16 libraries manually, these are the
- steps required to do so under Linux or Mac OS X (cygwin might work as well,
- but is untested):
+ Should you require to rebuild the pic16 libraries manually (e.g.
+ in order to enable output of float values
+\begin_inset LatexCommand index
+name "Floating point support"
+
+\end_inset
+
+ via 
+\family typewriter
+printf()
+\family default
+, see below), these are the steps required to do so under Linux or Mac OS
+ X (cygwin might work as well, but is untested):
 \end_layout
 
 \begin_layout LyX-Code
 \end_layout
 
 \begin_layout LyX-Code
@@ -27295,6 +27390,54 @@ cd device/include
 su -c 'make install'     # install the headers, you need the root password
 \end_layout
 
 su -c 'make install'     # install the headers, you need the root password
 \end_layout
 
+\begin_layout Subsubsection*
+Output of float values via printf()
+\end_layout
+
+\begin_layout Standard
+The library is normally built without support for displaying float values,
+ only <NO FLOAT> will appear instead of the value.
+ To change this, rebuild the library as stated above, but call 
+\family typewriter
+./configure.gnu --enable-floats 
+\family default
+instead of just 
+\family typewriter
+./configure.gnu
+\family default
+.
+ Also make sure that at least 
+\family typewriter
+libc/stdio/vfprintf.c
+\family default
+ is actually recompiled, e.g.
+ by 
+\family typewriter
+touch
+\family default
+ing it after the 
+\family typewriter
+configure
+\family default
+ run or deleting its 
+\family typewriter
+.o
+\family default
+ file.
+\end_layout
+
+\begin_layout Standard
+The more common appraoch of compiling 
+\family typewriter
+vfprintf.c
+\family default
+ manually with 
+\family typewriter
+-DUSE_FLOATS=1
+\family default
+ should also work, but is untested.
+\end_layout
+
 \begin_layout Subsection
 Adding New Devices to the Port
 \end_layout
 \begin_layout Subsection
 Adding New Devices to the Port
 \end_layout