<commit_before>%
% introduction
%

\newpage
\section{Background and History}

\liquid\ is a free and open-source digital signal processing (DSP) library
designed specifically for software-defined radios on embedded platforms.
The aim is to provide a lightweight DSP library that does not rely on a myriad
of external dependencies or proprietary and otherwise cumbersome frameworks.
%
All signal processing elements are designed to be flexible, scalable, and
dynamic, including filters, filter design, oscillators, modems, synchronizers,
and complex mathematical operations.
The source for \liquid\ is written entirely in C so that it can be
compiled quickly with a low memory footprint
and easily deployed on embedded platforms.

\liquid\ was created by <NAME> in 2007 out of necessity to perform
complex digital signal processing algorithms on embedded devices
with a low memory footprint and little computational overhead.
This was a critical step in his PhD thesis to adapt DSP algorithms in
cognitive dynamic-spectrum radios to optimally manage finite radio resources.
The project is not intended to compete with many other well-known and
excellent software radio packages freely available
(such as {\em GNU radio} \cite{gnuradio:web} and {\em OSSIE}
\cite{ossie:web})
but was created as a lightweight library which can be used to augment
these projects' capabilities
or be used in embedded platforms were minimizing overhead is critical.
You will notice that \liquid\ lacks any sort of underlying framework
%found in these packages
for connecting signal processing ``blocks'' or ``components.''
The design was chosen because each application requires the signal
processing block to be redesigned and recompiled for each application
anyway so the notion of a reconfigurable framework is, for the most
part, a flawed concept.
%A large number of researchers want the functionality found in scripted
%languages such as MATLAB \cite{mathworks:web} or GNU Octave
%\cite{octave:web} but need to speed of a real-time processing library so
%that they can test their algorithms in real wireless environments.

In \liquid\ there is
no model for passing data between structures,
no generic interface for data abstraction,
no customized/proprietary data types,
no framework for handling memory management;
this responsibility is left to the designer,
and as a consequence the library provides very little computational overhead.
% TODO : reword [provides] above
% ...
This package does {\em not} provide
graphical user interfaces,
component models, or
debugging tools;
\liquid\ is simply a collection raw signal processing modules
providing flexibility in algorithm development for wireless
communications at the physical layer.


% Key points
%   * open-source software-defined radio DSP algorithms
%   * minimal dependence on external libraries
%   * portable to embedded platforms
%   * flexible configuration
%   * targets cognitive radios and enabling technologies through
%     flexible algorithmic development
%
% Features
%   * automatic test scripts for validation and accuracy
%   * benchmark tool for estimating computational speed on your machine
%

\section{Quick Start Guide}
\label{section:quickstart}
A full description of installation procedures can be found in
Part~\ref{part:installation}.
%\S\ref{section:installation}.
The library can easily be built from source and is available from
several places.
The two most typical means of distribution are a compressed archive
(a {\em tarball}) and cloning the source repository.
If you are building from a tarball
download the compressed archive {\tt liquid-dsp-v.v.v.tar.gz} to your
local machine where {\tt v.v.v} denotes the version of the release
(e.g. {\tt liquid-dsp-\liquidversion.tar.gz});
% Check the validity of the tarball using MD5...
%
% generate:
%   $ md5sum liquid-dsp-v.v.v.tar.gz > liquid-dsp.md5
%
% check:
%   $ md5sum --check liquid-dsp.md5
%
% You should see a message verifying the file:
%   liquid-dsp-v.v.v.tar.gz: OK
%
% If it fails, do no unpack.
Unpack the tarball
%
\begin{verbatim}
    $ tar -xvf liquid-dsp-v.v.v.tar.gz
\end{verbatim}
%
Move into the directory and run the configure script and make the
library.
%
\begin{verbatim}
    $ cd liquid-dsp-v.v.v
    $ ./configure
    $ make
    # make install
\end{verbatim}
%
You may also build the latest version of the code by cloning the
Git repository.
The main repository for \liquid\ is hosted online by {\em github}
\cite{github:web} and can be cloned on your local machine via
%
\begin{verbatim}
    $ git clone git://github.com/jgaeddert/liquid-dsp.git
\end{verbatim}
%
Move into the directory, check out a particular tag, and build as before
with the archive, but with the additional bootstrapping step:
%
\begin{verbatim}
    $ cd liquid-dsp
    $ git checkout v1.2.0
    $ ./reconf
    $ ./configure
    $ make
    # make install
\end{verbatim}
%
You might also want to build and run the optional validation program
(see \S\ref{section:installation:targets:autotests}) via
\begin{verbatim}
    $ make check
\end{verbatim}
and the benchmarking tool
(see \S\ref{section:installation:targets:benchmarks})
\begin{verbatim}
    $ make bench
\end{verbatim}
%
A comprehensive list of signal processing examples is given in the
{\tt examples} directory.
You may build all of the example binaries at one time by running
\begin{verbatim}
    $ make examples
\end{verbatim}
%
Sometimes, however, it is useful to build one example individually.
This can be accomplished by directly targeting its binary
(e.g. ``{\tt make examples/cvsd\_example}'').
The example then can be run at the command line
(e.g. ``{\tt ./examples/cvsd\_example}'').
<commit_msg>doc: separating build steps in quick start guide using subsections<commit_after>%
% introduction
%

\newpage
\section{Background and History}

\liquid\ is a free and open-source digital signal processing (DSP) library
designed specifically for software-defined radios on embedded platforms.
The aim is to provide a lightweight DSP library that does not rely on a myriad
of external dependencies or proprietary and otherwise cumbersome frameworks.
%
All signal processing elements are designed to be flexible, scalable, and
dynamic, including filters, filter design, oscillators, modems, synchronizers,
and complex mathematical operations.
The source for \liquid\ is written entirely in C so that it can be
compiled quickly with a low memory footprint
and easily deployed on embedded platforms.

\liquid\ was created by <NAME> in 2007 out of necessity to perform
complex digital signal processing algorithms on embedded devices
with a low memory footprint and little computational overhead.
This was a critical step in his PhD thesis to adapt DSP algorithms in
cognitive dynamic-spectrum radios to optimally manage finite radio resources.
The project is not intended to compete with many other well-known and
excellent software radio packages freely available
(such as {\em GNU radio} \cite{gnuradio:web} and {\em OSSIE}
\cite{ossie:web})
but was created as a lightweight library which can be used to augment
these projects' capabilities
or be used in embedded platforms were minimizing overhead is critical.
You will notice that \liquid\ lacks any sort of underlying framework
%found in these packages
for connecting signal processing ``blocks'' or ``components.''
The design was chosen because each application requires the signal
processing block to be redesigned and recompiled for each application
anyway so the notion of a reconfigurable framework is, for the most
part, a flawed concept.
%A large number of researchers want the functionality found in scripted
%languages such as MATLAB \cite{mathworks:web} or GNU Octave
%\cite{octave:web} but need to speed of a real-time processing library so
%that they can test their algorithms in real wireless environments.

In \liquid\ there is
no model for passing data between structures,
no generic interface for data abstraction,
no customized/proprietary data types,
no framework for handling memory management;
this responsibility is left to the designer,
and as a consequence the library provides very little computational overhead.
% TODO : reword [provides] above
% ...
This package does {\em not} provide
graphical user interfaces,
component models, or
debugging tools;
\liquid\ is simply a collection raw signal processing modules
providing flexibility in algorithm development for wireless
communications at the physical layer.


% Key points
%   * open-source software-defined radio DSP algorithms
%   * minimal dependence on external libraries
%   * portable to embedded platforms
%   * flexible configuration
%   * targets cognitive radios and enabling technologies through
%     flexible algorithmic development
%
% Features
%   * automatic test scripts for validation and accuracy
%   * benchmark tool for estimating computational speed on your machine
%

\section{Quick Start Guide}
\label{section:quickstart}
A full description of installation procedures can be found in
Part~\ref{part:installation}.
%\S\ref{section:installation}.
The library can easily be built from source and is available from
several places.
The two most typical means of distribution are a compressed archive
(a {\em tarball}) and cloning the source repository.

\subsection{Building from a Tarball}
\label{section:quickstart:tarball}
If you are building from a tarball
download the compressed archive {\tt liquid-dsp-v.v.v.tar.gz} to your
local machine where {\tt v.v.v} denotes the version of the release
(e.g. {\tt liquid-dsp-\liquidversion.tar.gz}).
% 
% Download the tarball and md5 check:
%
%   $ wget http://ganymede.ece.vt.edu/downloads/liquid-dsp-version.tar.gz
%   $ wget http://ganymede.ece.vt.edu/downloads/liquid-dps.md5
%   $ md5sum --check liquid-dsp.md5
%
% Check the validity of the tarball using MD5...
%
% generate:
%   $ md5sum liquid-dsp-v.v.v.tar.gz > liquid-dsp.md5
%
% check:
%   $ md5sum --check liquid-dsp.md5
%
% You should see a message verifying the file:
%   liquid-dsp-v.v.v.tar.gz: OK
%
% If it fails, do no unpack.
Unpack the tarball
%
\begin{verbatim}
    $ tar -xvf liquid-dsp-v.v.v.tar.gz
\end{verbatim}
%
Move into the directory and run the configure script and make the
library.
%
\begin{verbatim}
    $ cd liquid-dsp-v.v.v
    $ ./configure
    $ make
    # make install
\end{verbatim}
%

\subsection{Cloning the Git Repository}
\label{section:quickstart:git}
%
You may also build the latest version of the code by cloning the
Git repository.
The main repository for \liquid\ is hosted online by {\em github}
\cite{github:web} and can be cloned on your local machine via
%
\begin{verbatim}
    $ git clone git://github.com/jgaeddert/liquid-dsp.git
\end{verbatim}
%
Move into the directory, check out a particular tag, and build as before
with the archive, but with the additional bootstrapping step:
%
\begin{verbatim}
    $ cd liquid-dsp
    $ git checkout v1.2.0
    $ ./reconf
    $ ./configure
    $ make
    # make install
\end{verbatim}
%

\subsection{Additional {\tt make} Targets}
\label{section:quickstart:targets}
%
You might also want to build and run the optional validation program
(see \S\ref{section:installation:targets:autotests}) via
\begin{verbatim}
    $ make check
\end{verbatim}
and the benchmarking tool
(see \S\ref{section:installation:targets:benchmarks})
\begin{verbatim}
    $ make bench
\end{verbatim}
%
A comprehensive list of signal processing examples is given in the
{\tt examples} directory.
You may build all of the example binaries at one time by running
\begin{verbatim}
    $ make examples
\end{verbatim}
%
Sometimes, however, it is useful to build one example individually.
This can be accomplished by directly targeting its binary
(e.g. ``{\tt make examples/cvsd\_example}'').
The example then can be run at the command line
(e.g. ``{\tt ./examples/cvsd\_example}'').

{'fraction_non_alphanumeric': 0.07203639733760216, 'fraction_numerical': 0.002359086696436094, 'mean_word_length': 4.351668169522092, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 5, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '640065', 'n_tokens_mistral': 3333, 'n_tokens_neox': 3143, 'n_words': 1525}