BUILDING AND INSTALLING DECODING

OVERVIEW

This page describes how to build the library and how to install it. In many cases it is sufficient to type make && make install in the root directory of decoding to build and install it. If it does not work please read the following.

DESCRIPTION

The decoding library is written in C89 and should therefore be build without trouble by any C compiler which supports strict C89. The library has been tested on several linux distributions and on Mac OS.

Debian 7.0 (64 bits)
Archlinux (64 bits)
Scientific Linux 6.3 (64 bits)
Mac OS X v10.6.8 (32 bits)

HOW TO BUILD THE LIBRARY?

As of now, no Makefile-building system is available. Dependencies must be dealt with by hand but it is easy! The beginning of the main Makefile has to be modified and only the beginning of the Makefile. In fact reading the Makefile should be sufficient to do all you have/want to do to build and install the library and you can skip this page.

Otherwise, when you have decompressed the library, the beginning of the Makefile looks like:

############################################################
#
# Here is where you want to set paths for external
# libraries and installation and customize other stuff.
#
############################################################

# Directories for GMP (this is mandatory, if GMP is not
# present on your system, you won't be able to compile
# decoding)
GMP_CFLAGS        =
GMP_LDFLAGS       = -lgmp

# Directories for MPFQ (this is NOT mandatory)
MPFQ_GF2N_CFLAGS  = 
MPFQ_GF2N_LDFLAGS = -lmpfq_gf2n

# Directories for GF2X (this is NOT mandatory)
GF2X_CFLAGS       =
GF2X_LDFLAGS      = -lgf2x

# Installation directories
LIB_DIR           = /usr/lib
INCLUDE_DIR       = /usr/include
MAN_DIR           = /usr/share/man/man3

# Optimizations/debug flags
#CUSTOM_FLAGS      = -g
#MULTI_THREADING   = -fopenmp
#INDEX_TYPE        = int # must be int or long

Once you will have modified the Makefile to suit your needs simply type

make

to build the library and then

make install

to install the library. It is recommended to do make check before using the library. Note that it can last several hours. If you do not have time or any patience it is strongly recommended that you do make check-mini which will only check all the decoding algorithms provided by the library. It should last at most five minutes.

DEPENDENCIES

As indicated by the comments in the Makefile, the library depends on one mandatory external library and two optional library.

GMP is the only mandatory dependency. It should be present on your system by default. Do not forget to install the development package of GMP. For example type
```
sudo aptitude install libgmp-dev
```
in a Debian box. Please refer to the documentation of your system to install the development files for GMP. If you are not root or if the GMP header files are not located in their standard directories for your system you will have to modify the main Makefile as follows.
```
# Directories for GMP (this is mandatory, if GMP is not
# present on your system, you won't be able to compile
# decoding)
GMP_CFLAGS        = -I/path/to/gmp/headers
GMP_LDFLAGS       = -L/path/to/gmp/binary -lgmp
```
Here /path/to/gmp/binary/ is the path where the binary for GMP is and /path/to/gmp/headers/ is the path where the headers of GMP are.
MPFQ is an optional dependency. It is an effecient library for doing the arithmetic of finite fields with an emphasize for finite fields of characteristic 2. By default if you leave the MPFQ_GF2N_CFLAGS variable empty in the Makefile, the library will consider that MPFQ is not present present on your system and will be built accordingly even if MPFQ is present on your system.

If you want decoding to use MPFQ you have to modify the Makefile as follows.
```
# Directories for MPFQ (this is NOT mandatory)
MPFQ_GF2N_CFLAGS  = -I/path/to/mpfq/headers
MPFQ_GF2N_LDFLAGS = -L/path/to/mpfq/binary -lmpfq_gf2n
```
Here /path/to/mpfq/binary/ is the path where the binary for MPFQ is and /path/to/mpfq/headers/ is the path where the headers of MPFQ are. Note that if you have installed MPFQ on the standard directories for your system, for example if the header files are located in /usr/include and the binary files in /usr/local/lib, you simply have to modify the MPFQ_GF2N_CFLAGS variable as follows.
```
# Directories for MPFQ (this is NOT mandatory)
MPFQ_GF2N_CFLAGS  = -I/usr/include
MPFQ_GF2N_LDFLAGS = -lmpfq_gf2n
```
GF2X is an optional dependency. It is a library containing routines for doing fast arithmetic in GF(2)[x] (multiplication, squaring, GCD) and searching for irreducible/primitive trinomials. By default if you leave the GF2X_CFLAGS variable empty in the Makefile, the library will consider that GF2X is not present present on your system and will be built accordingly even if GF2X is present on your system.

If you want decoding to use GF2X you have to modify the Makefile as follows.
```
# Directories for GF2X (this is NOT mandatory)
GF2X_CFLAGS  = -I/path/to/gf2x/headers
GF2X_LDFLAGS = -L/path/to/gf2x/binary -lgf2x
```
Here /path/to/gf2x/binary/ is the path where the binary for GF2X is and /path/to/gf2x/headers/ is the path where the headers of GF2X are. Note that if you have installed GF2X on the standard directories for your system, for example if the header files are located in /usr/include and the binary files in /usr/local/lib, you simply have to modify the GF2X_CFLAGS variable as follows.
```
# Directories for GF2X (this is NOT mandatory)
GF2X_CFLAGS  = -I/usr/include
GF2X_LDFLAGS = -lgf2x
```

INSTALLATION

The library binary files go, by default, into /usr/lib, the header files go into /usr/include and the manpages go into /usr/share/man/man3. You can of course install decoding files where you want. You simply have to modify the Makefile.

# Installation directories
LIB_DIR           = /usr/lib
INCLUDE_DIR       = /usr/include
MAN_DIR           = /usr/share/man/man3

The LIB_DIR variable determines where the binary files will be installed. The INCLUDE_DIR variable determines where the header files will be installed. The MAN_DIR variable determines where the manpages will be installed.

CUSTOMIZATION FOR COMPILATION

The CUSTOM_FLAGS variable let you choose the compile flags to give the compiler. If you leave this variable empty the Makefile will determine the best compile flags. If you have trouble building the library, try with the following modification.

# Optimizations/debug flags
CUSTOM_FLAGS      = -O3

If you want to use gdb(1) and/or valgrind(1) to debug your programs using decoding set the CUSTOM_FLAGS variable as follows.

# Optimizations/debug flags
CUSTOM_FLAGS      = -g -O3

Other variables are present in the Makefile and should not be modified.

#MULTI_THREADING   = -fopenmp
#INDEX_TYPE        = int # must be int or long

The MULTI_THREADING variable controls whether some algorithms in decoding should be parallelized or not. If so, then the parallelization is done with the OpenMP directives. Parallelization should not be set as it is still experimental. The INDEX_TYPE variable controls which C integer type (either signed int or signed long) is to be used for array indexing. By default long is used and it is recommanded that you do not modify this value.

USING DECODING WITH C++

The library can be used by any C++ program. Just build the library as described above. You are then free to use it as any C library with a C++ program. The way to use the library does not change. All functions provided by the library are within the namespace decoding.

#include <decoding/decoding.h>

#define RING_NAME F
#include <decoding/rings/GF5.c>
#include <decoding/algos.c>

using namespace decoding;

int main(void) {
  F a;
  ll_random_seed(time(NULL));
  F_ring_init();
  F_random(a);
  F_ll_print(stdout,"%en",a);
  F_ring_clear();
  return 0;
}

AUTHOR

Written by Guillaume Quintin (quintin@lix.polytechnique.fr).