%
%	%Z% %G% %I% %M%
%

\documentclass[12pt,a4paper,titlepage]{article}
\usepackage{lscape}
\usepackage{ifpdf}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
% \usepackage{newcent}
\usepackage{mathptmx}
\usepackage[scaled=.92]{helvet}
\usepackage{courier}
\usepackage{array}
\usepackage{enumerate}
\usepackage{longtable}
\usepackage{latexsym}
\usepackage{varioref}
\usepackage{color}
\usepackage{listings}
\ifpdf
\usepackage[activate=normal]{pdfcprot}
\usepackage[pdftex]{graphicx}
\usepackage{epstopdf}
\pdfcompresslevel=9
\usepackage[
  pdftex,
  a4paper=true,
  pdftitle={Dklibs installation on Windows},
  pdfsubject={Dklibs installation on Windows},
  pdfauthor={Dipl.-Ing. D. Krause},
  colorlinks=true,
  linkcolor=black,
  pdfpagemode=None,
  pdfstartview=FitH
]{hyperref}
\else
\usepackage[dvips]{graphicx}
\DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1}
\usepackage[
  dvips,
  colorlinks=true,
  linkcolor=black
]{hyperref}
\fi
% \renewcommand*{\sectfont}{\bfseries}
\parindent0cm
\author{Dipl.-Ing.~D.~Krause}
\title{Dklibs installation on Windows}

\def\leftsideofhandler{0.45\linewidth}
\def\rightsideofhandler{0.55\linewidth}

\newcommand{\ximagelw}[3]{
  \begin{figure}[htb]
  {\centering
    \includegraphics[width=#1\linewidth]{#2.mps}
    \caption{#3}
    \label{fig:#2}
  }
  \end{figure}
}

\begin{document}
\maketitle
\cleardoublepage
\ifpdf\pdfbookmark[1]{\contentsname}{tocanc}\fi
\tableofcontents
\cleardoublepage
\section{Overview}
This manual tries to give you hints to install dklibs and some of
the applications based on these libraries on a Windows system.\\
Figure~\vref{fig:depgr} shows the dependencies between the packages.
\ximagelw{}{depgr}{Software dependencies}
\clearpage
\section{Software and skills needed for the build}
To build the software you need an ANSI-C-compiler, a linker and
a ``make'' program. There are several development suites available,
both commercial software (MS Visual Studio, Borland/Imprise products)
and open-source software (Cygwin, MingW).

To build OpenSSL from source you also need a working Perl distribution.
I suggest to use ActivePerl \footnote{see \url{http://www.activestate.com}}.
An assembler is helpful to build OpenSSL, you can use either
MASM (available via platform SDK) or NASM.

You should have a working knowledge about:
\begin{itemize}
\item	the command line options of the C compiler, linker and
	make program you use and
\item	the structure of makefiles.
\end{itemize}
\clearpage

\section{Some decisions before starting to install}
Before you start any build process you have to decide whether
you want to have statically linked software or dynamically
linked software.

I recommend static linking.

Using MS Visual C you have several versions of the C run-time library
available. The preferred run-time library file for each source
module is choosen by \emph{compiler} switches when compiling the module.



\begin{longtable}{|c|l|}
\caption{Command line switches to choose run-time library}
\label{tab:keys-for-features}
\\
%
\hline
&\\*[-0.95em]\multicolumn{1}{|c|}{\textbf{Switch}} & \multicolumn{1}{c|}{\textbf{File}}\\
\hline
\endfirsthead
%
\hline
&\\*[-0.95em]\multicolumn{2}{|r|}{\small \textsl{Continuation}}\\
\hline
\endhead
%
&\\*[-0.95em]\multicolumn{2}{|r|}{\small \textsl{\ldots{}to be continued}}\\
\hline
\endfoot
%
\hline
\endlastfoot
%
\hline
&\\*[-0.95em]/ML & LIBC.LIB (static, release, single-threaded)\\*
\hline
&\\*[-0.95em]/MLd & LIBCD.LIB (static, debug, single-threaded)\\*
\hline
&\\*[-0.95em]/MT & LIBCMT.LIB (static, release, multi-threaded)\\*
\hline
&\\*[-0.95em]/MTd & LIBCMTD.LIB (static, debug, multi-threaded)\\*
\hline
&\\*[-0.95em]/MD & MSVCRT.LIB (DLL, release)\\*
\hline
&\\*[-0.95em]/MDd & MSVCRTD.LIB (DLL, debug)\\*
\end{longtable}

Object modules contain an information which run-time library they want
to be linked with. During linking the linker inspects all object
files -- even those in libraries -- and tries to use all the run-time
libraries mentioned in any object module. If two (or more) modules
were compiled specifying a different run-time library the linker
will report conflicts and abort.\\
Conclusion: You need to use the same run-time library selection
switch for all objects (both for installing the required/recommended
libraries and installing dklibs and software based on it).\\
I recommend to use ``/MT'' for static linking or ``/MD'' for
DLL-linking.

As pointed out you need to use the same run-time selection switch
for all packages to build. When building DLL verions of
the required/recommended libraries our compiler switches might differ
from the compiler switches used to build the ``official'' DLL.
If you have other software installed built to use one of the ``official'' DLLs
strange things might happen if this software finds our self-made
DLLs instead. That's why I recommend to use static linking.
\clearpage

\section{Installing the required/recommended libraries}
\subsection{Installation order}
I suggest to build the libraries in the following order:
\begin{itemize}
\item	zlib\\*\url{http://www.gzip.org/zlib}\\*This library can be used
	by the dklibs library set to access gzip compressed files. If you
	want to build bmeps or png2pdf this library is required.
\item	bzip2\\*\url{http://sources.redhat.com/bzip2}\\*This library
	can be used by the dklibs library set to access bzip2 compressed files.
\item	libpng\\*\url{http://www.libpng.org}\\*
	This library is used by bmeps and png2pdf to read PNG images. It is
	required to build these packages.
\item	JPEG lib\\*\url{ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz}
	This library can used by bmeps to read JPEG files, it is optional.
\item	NetPBM lib\\*\url{ftp://ftp.metalab.unc.edu/pub/Linux/apps/graphics/convert/netpbm-10.11.10.tgz}\\*
	This library can be used by bmeps to read NetPBM images, it is
	optional. The NetPBM tools allow to convert a wide variety
	of bitmap graphics formats to the NetPBM formats.
\item	OpenSSL\\*\url{http://www.openssl.org}\\*
	This library can be used by the kls application to calculate
	and print message digests (checksums) for files, it is optional.
	The Net-SNMP library can optionally use OpenSLL for authentication.
\item	Net-SNMP\\*\url{http://net-snmp.sourceforge.net}\\*
	This library can optionally be used by the yanolc package to build the
	snmpyalc program to request printer status information via SNMP.
	If none of your printers has a direct ethernet connection
	via internal print servers (i.e. HP JetDirect interface) the
	snmpyalc will probably not be usefull for you.
\end{itemize}
It is not in all cases necessary to install all libraries, see
figure~\vref{fig:depgr} for package dependencies.
\clearpage
\subsection{General instructions}
\subsubsection{Makefile modifications}
The library archives contain makefiles named ``makefile.msc'' or
``makefile.vc'' for use with MS Visual C++. Additionally there are
build instructions in readme files, file names differ.

To build the libraries follow the instructions in the readme files,
but before running ``nmake'' or ``make'' modify the
makefile manually:
\begin{itemize}
\item	Open the makefile in a text editor,
\item	Search for a section introduced by a line
	\begin{lstlisting}
	.c.obj:
	\end{lstlisting}
\item	The line after ``.c.obj:'' specifies the command to invoke
	the C compiler. You need to remove any command line
	switch choosing a C run-time library version and replace
	it by the switch you have decided to use in all the builds.
\item	Sometimes the command line switches are not specified directly,
	a macro expansion mechanism is used instead.\\
	If the command line looks like
	\begin{lstlisting}
	CL $(CFLAGS) /c $*.c
	\end{lstlisting}
	you have to search for a line started by ``CFLAGS='' to do the
	replacements there.
\end{itemize}
\subsubsection{Building the libraries}
To build the libraries run
\begin{lstlisting}
  nmake -f makefile.msc
\end{lstlisting}
The name of the makefile may differ. For some of the libraries
it is usefull to give the name of the library to build on the
command line, i.e.
\begin{lstlisting}
  nmake -f makefile.msc libbz2.lib
\end{lstlisting}
\subsubsection{Copying files in place}
If you are doing static builds, create a directory
``c:\textbackslash{}p\textbackslash{}lib-stt'', for a DLL-based build
use ``c:\textbackslash{}p\textbackslash{}lib-dll''. Create subdirectories
``lib'', ``include'' and ``bin''. Do the following copy operations
\begin{lstlisting}
  xcopy *.h   c:\p\lib-stt\include\ /Y
  xcopy *.lib c:\p\lib-stt\lib\     /Y
  xcopy *.exe c:\p\lib-stt\bin\     /Y
\end{lstlisting}
For a DLL-based build this loooks like
\begin{lstlisting}
  xcopy *.h   c:\p\lib-dll\include\ /Y
  xcopy *.lib c:\p\lib-dll\lib\     /Y
  xcopy *.dll c:\p\lib-dll\bin\     /Y
  xcopy *.exe c:\p\lib-dll\bin\     /Y
\end{lstlisting}

\subsection{Library-specific instructions}
\subsubsection{LibPNG}
The makefile.msc assumes to find the zlib library in ``../zlib''.
We have installed zlib in subdirectories of
``C\textbackslash{}p\textbackslash{}lib-stt''
so we need to correct the makefile entry to
``-I"C:\textbackslash{}p\textbackslash{}lib-stt\textbackslash{}include"''.
For a DLL-build replace ``lib-stt'' by ``lib-dll''.
\subsubsection{JPEG library}
The JPEG library is shipped without a *.def file for DLL building.
The contrib/jpeg directory in bmeps contains a ``jpeg.def'' file.
\clearpage
\subsubsection{NetPBM library}
The NetPBM library is shipped without a *.def file too.
The contrib/netpbm directory in bmeps contains a ``netpbm.def'' file.

To build the NetPBM library unpack the sources archive and go
into the ``lib'' subdirectory. Copy all the files from the ``util''
subdirectory into the ``lib'' directory.

Edit the ``shhopt.c'' file, add the function
\begin{lstlisting}
char *rindex(char *s, int c)
{
   char *back = NULL;
   char *ptr;
   ptr = s;
   while(*ptr) {
    if(*ptr == c) {
     back = ptr;
    }
    ptr++;
   }
   return back;
}
\end{lstlisting}

Edit the file ``libpm.c'' and add the following two sections:
\begin{lstlisting}
#include <io.h>
#include <process.h>
#include <stdlib.h>
\end{lstlisting}
\begin{lstlisting}
static int _S_ISREG(int m)
{
  int back = 0;
  if((m & _S_IFMT) == _S_IFREG) {
    back = 1;
  }
  return back;
}
\end{lstlisting}
\clearpage
\subsubsection{OpenSSL}
The makefiles ``nt.mak'' and ``ntdll.mak'' are generated 
(or possibly renewed) by the
\begin{lstlisting}
  perl Configure VC-WIN32
  ms\do_masm
\end{lstlisting}
commands. You have to edit the makefiles to set up the run-time
library version after running the two commands above and before running
\begin{lstlisting}
  nmake -f ms\nt.mak
\end{lstlisting}
or
\begin{lstlisting}
  nmake -f ms\ntdll.mak
\end{lstlisting}
Additionally remove all the optimization/warning related compiler
flags and add ``-DOPENSSL\_NO\_HW\_PADLOCK=1 /Zm1000'' to increase the used memory pool for the
compiler and to disable inline-assembling of eng\_padlock.c.\\
For the static library we should have
\begin{lstlisting}
CFLAGS= /MT /nologo -DOPENSSL_SYSNAME_WIN32 ... \
  -DOPENSSL_NO_KRB5 -DOPENSSL_NO_HW_PADLOCK=1 /Zm1000
\end{lstlisting}
\subsubsection{Net-SNMP}
The Net-SNMP library archive contains a project/workspace for
MSVC. When following the instructions in the readme you will possibly
add OpenSLL support. Among other things you need to add the libraries
``libeay32.lib'' and ``ssleay32.lib'' to all the projects. Make sure
that ``gdi32.lib'' is also included. Newer version of Net-SNMP
use the ``gdi32.lib'' library (I do not know exactly but I think
it is to get entropy from the screen).
Somewhere in the project settings you can change the setting for
the C run-time. Switch this to the library you have decided to use
for all the projects.
\clearpage
\section{Dklibs and applications}
You have to install the dklibs library set before you try bo build
any application using it.
There is no specific order to build the applications, choose as you
want.

The archives contain a file named ``makefile.msc''. Each of these
makefiles has two configuration sections possibly needing modifications.
\begin{itemize}
\item	The first configuration section is at the beginning of the
	file. This section is used for
	\begin{itemize}
	\item	locations of directories and
	\item	subsections to indicate which libraries are available.
	\end{itemize}
	The subsections for required libraries are ready-to-use.
	Subsections for recommended libraries must be toggled to use
	the library. Toggling such a subsection means to add a
	comment sign (``\#'') in front of all lines not started by ``\#''.
	For all lines started by ``\#'' remove the leading ``\#''.\\*
	Note: a subsection ends at an empty line.
\item	The second configuration section contains information how to
	build libraries: either DLL-linked or statically linked.
	The default is static linking, toggle all the subsection
	to switch to DLL-linking.\\*
	Switching to DLL-linking also requires to toggle some lines
	in the first configuration section to activate the installation
	commands to copy *.DLL files into the right places. For zlib
	we also need to correct the name of the linker import library.
\end{itemize}
\end{document}

