\documentclass{article}

\usepackage[margin=0.8in]{geometry}
\usepackage[T1]{fontenc}
\usepackage{xhfill,textcomp}
\usepackage[
        colorlinks=true,
        allcolors=darkgray
]{hyperref}

\title{Building Allegro on Linux}
\author{Introduction to Programming, University of York}

\newcommand{\suprg}{\textsuperscript{\textregistered}}
\newcommand{\suptm}{\textsuperscript{\texttrademark}}

\begin{document}

\makeatletter
\large\textbf{\@title}\quad\xrfill[0.5ex]{0.5pt}[lightgray]%
\quad\textit{\@author}
\makeatother

\vspace{1em}

\normalsize
\begin{enumerate}
        \item \textit{Download the sources from GitHub.}

        This is ideally done with the \textit{git} VCS, however grabbing a
        zipped snapshot of the repository head via HTTP is an option for users
        lacking a copy of \textit{git}.  Choose the appropriate method for your
        environment and execute \textit{one} of the following the commands in a
        shell:

        \begin{itemize}
                \item \texttt{git clone https://github.com/liballeg/%
                        allegro5.git}
                \item \texttt{wget https://github.com/liballeg/allegro5/%
                        archive/refs/heads/master.zip}
        \end{itemize}

        If the second method was chosen, unzip and rename the sources:

        \begin{itemize}
                \item \texttt{unzip -q master.zip \&\&
                        mv allegro5-master allgero5 \&\& rm master.zip}
        \end{itemize}

        \item \textit{Navigate into the sources and create the build directory.}

        \begin{itemize}
                \item \texttt{cd allegro5 \&\& mkdir build \&\& cd build}
        \end{itemize}

        \item \textit{Configure the sources to determine the availability of
                dependencies on your system.}

        \begin{itemize}
                \item \texttt{cmake{ }..}
        \end{itemize}

        Always review the configuration summary for any obvious mistakes. Most
        reasonable systems will have the majority of necessary libraries
        installed, however users running minimal installations, such as kernels
        cloned directly from \texttt{kernel.org}, or those without a windowing
        system, may have to do additional work to satisfy the minimum set of
        dependencies. Some libraries perform similar functions, such as
        \texttt{OSS}, \texttt{PulseAudio}, and \texttt{ALSA}, so users needn't
        worry if only one of these dependencies is satisfied.

        \item \textit{Build the sources.}

        \begin{itemize}
                \item \texttt{make}
        \end{itemize}

        At this stage, all temporary build files have been generated by the
        configuration script, so no errors should occur. Compilation and linking
        is a CPU-intensive job, especially for large libraries like Allegro, so
        this operation may take a while\footnote{6m:50s on an Intel\suprg{}
        Core\suptm{} 2 P8400 @ 2.26GHz and 0m:26s on an Intel\suprg{}
        Core\suptm{} i7-5820K @ 3.30GHz. Users familiar with \texttt{make} may
        wish to make use of the \texttt{-j} parallelisation option to
        significantly reduce build time; use \texttt{grep cpu\textbackslash\
        cores -m 1 /proc/cpuinfo} to determine the number of available CPU
        cores.}.

        \item \textbf{(Optional: requires root access.)}
                \textit{Install the binaries.}

        For users wishing to configure a more permanent Allegro development
        environment, it is highly recommended to place the generated shared
        object files, which currently exist inside \texttt{build/lib}, inside
        the standard system path. Symbolic links are generated to support the
        standard UNIX semantic versioning schema. By installing the sources,
        they are being placed into the system library directory; typically
        \texttt{/usr/lib}, \texttt{/usr/lib64}, or \texttt{/usr/local/lib} for
        easy use by any linker operating on the filesystem. This is especially
        important in the case of dynamic linking.

        \begin{itemize}
                \item \texttt{make install}
        \end{itemize}

        If this stage is not completed, users wishing to link to Allegro must
        explicitly specify the absolute location of the \texttt{build/}
        directory.

        \item \textit{Building a Test Program with Allegro.}

        At this stage, the development headers and library binaries exist
        somewhere on your system. If you completed the \texttt{make install}
        stage, the headers reside in \texttt{/usr/local/include} and the
        binaries reside in \texttt{/usr/local/lib}. If the installation stage
        was not completed, the headers exist in the original repository's
        \texttt{include/allegro5} directory, with the binaries in
        \texttt{build/lib}. Now we must perform two stages: informing the
        runtime linker to the location of the shared objects (for dynamic
        linking), and provide the include and build directories to the linker at
        compiletime.

        \begin{enumerate}
                \item To allow for runtime linking, the linker must be aware of
                        the binaries' location. This is done by appending the
                        \texttt{/usr/local/lib} or absolute \texttt{build/lib}
                        path to the environment variable
                        \texttt{LD\_LIBRARY\_PATH}. Assuming Bash, enter the
                        following commands to permanently update the
                        environment:
                        \begin{enumerate}
                                \item \texttt{echo \textquotesingle{}%
                                        LD\_LIBRARY\_PATH=\textquotedbl{}%
                                        \$LD\_LIBRARY\_PATH:/usr/local/lib%
                                        \textquotedbl\textquotesingle{} >{}>
                                        \textasciitilde/.bashrc}
                                \item \texttt{source \textasciitilde/.bashrc}
                        \end{enumerate}

                \item Alter the compilation command to include the
                        aforementioned hints. This will need to be replicated
                        for each build. Remember to alter \texttt{-I} and
                        \texttt{-L} accordingly to match your Allegro
                        installation; \texttt{test.c} should be replaced with
                        your real source files\footnote{The CFLAGS build path
                        can also be attained with
                        \texttt{PKG\_CONFIG\_PATH=/usr/local/lib/pkgconfig/
                        pkg-config -{}-cflags -{}-libs allegro-5}, altering
                        \texttt{PKG\_CONFIG\_PATH} accordingly. For makefiles,
                        calculating the compiler flags with \texttt{pkg-config}
                        is always the preferred method, as the \texttt{.pc}
                        files update with the library.}.
                        \begin{itemize}
                                \item \texttt{gcc test.c -I/usr/local/include
                                        -L/usr/local/lib -lallegro}
                        \end{itemize}
        \end{enumerate}

        You should now be able to run your Allegro-dependent program on your
        system by executing \texttt{./a.out}. To report any errors in this
        document, please e-mail \url{od641@york.ac.uk}\footnote{X11, OpenGL, and
        ALSA dependency failures may occur, but please do not report them to
        this e-mail address, as there are too many distributions and package
        manager arrangements to cover everything in this short document. Someone
        on-line will have had the same problem as you.}.
\end{enumerate}

\end{document}

