path: root/INSTALL

Installation Instructions
*************************

Copyright (C) 1994-1996, 1999-2002, 2004-2011 Free Software Foundation, Inc.
Copyright (C) 2013 Galois, Inc.

Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and this
notice are preserved.  This file is offered as-is, without warranty of any kind.

Basic Installation
==================

Briefly, the shell commands

    export VREP=/path/to/vrep/installation
    ./configure
    make
    make install

should configure, build, and install this package.

The `configure' shell script attempts to guess correct values for various
system-dependent variables used during compilation.  It uses those values to
create a `Makefile' in the top-level directory of the package, as well as the
`src' subdirectory.  It also creates a `config.h' file containing
system-dependent definitions.  Finally, it creates a shell script
`config.status' that you can run in the future to recreate the current
configuration, and a file `config.log' containing compiler output (useful mainly
for debugging `configure').

It can also use an optional file (typically called `config.cache' and enabled
with `--cache-file=config.cache' or simply `-C') that saves the results of its
tests to speed up reconfiguring.  Caching is disabled by default to prevent
problems with accidental use of stale cache files.

If you need to do unusual things to compile the package, please try to figure
out how `configure' could check whether to do them, and mail diffs or
instructions to the address given in the `README' so they can be considered for
the next release.  If you are using the cache, and at some point `config.cache'
contains results you don't want to keep, you may remove or edit it.

The file `configure.ac' is used to create `configure' by a program called
`autoconf'.  You need `configure.ac' if you want to change it or regenerate
`configure' using a newer version of `autoconf'.

The simplest way to compile this package is:

  1. If you have not done so already, install V-REP and the Boost file system
     library.

  2. Export the environment variable `VREP' such that it points to the top-level
     directory of your V-REP installation.

  3. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.

     Running `configure' might take a while.  While running, it prints
     some messages telling which features it is checking for.

  4. Type `make' to compile the package.

  5. Type `make install' to install the programs and any data files and
     documentation.

  6. You can remove the program object files from the source code directory by
     typing `make clean'.  To also remove the files that `configure' created (so
     you can compile the package for a different kind of computer), type `make
     distclean'.  There is also a `make maintainer-clean' target, but that is
     intended mainly for the package's developers.  If you use it, you may have
     to get all sorts of other programs in order to regenerate files that came
     with the distribution.

  7. You can also type `make uninstall' to remove the installed files again.

Compilers and Options
=====================

Some systems require unusual options for compilation or linking that the
`configure' script does not know about.  Run `./configure --help' for details on
some of the pertinent environment variables.

You can give `configure' initial values for configuration parameters by setting
variables in the command line or in the environment.  Here is an example:

     ./configure CC=c99 CFLAGS=-g LIBS=-lposix

Compiling For Multiple Architectures
====================================

You can compile the package for more than one kind of computer at the same time,
by placing the object files for each architecture in their own directory.  To do
this, you can use GNU `make'.  `cd' to the directory where you want the object
files and executables to go and run the `configure' script.  `configure'
automatically checks for the source code in the directory that `configure' is in
and in `..'.  This is known as a "VPATH" build.

With a non-GNU `make', it is safer to compile the package for one architecture
at a time in the source code directory.  After you have installed the package
for one architecture, use `make distclean' before reconfiguring for another
architecture.

On Mac OS X 10.5 and later systems, you can create libraries and executables
that work on multiple system types--known as "fat" or "universal" binaries--by
specifying multiple `-arch' options to the compiler but only a single `-arch'
option to the preprocessor.  Like this:

     ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
                 CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
                 CPP="gcc -E" CXXCPP="g++ -E"

This is not guaranteed to produce working output in all cases, you may have to
build one architecture at a time and combine the results using the `lipo' tool
if you have problems.

Installation Names
==================

By default, `make install' installs the package's libraries under
`/usr/local/lib'.  You can specify an installation prefix other than
`/usr/local' by giving `configure' the option `--prefix=PREFIX', where PREFIX
must be an absolute file name.

You can specify separate installation prefixes for architecture-specific files
and architecture-independent files.  If you pass the option
`--exec-prefix=PREFIX' to `configure', the package uses PREFIX as the prefix for
installing programs and libraries.  Documentation and other data files still use
the regular prefix.

In addition, if you use an unusual directory layout you can give options like
`--bindir=DIR' to specify different values for particular kinds of files.  Run
`configure --help' for a list of the directories you can set and what kinds of
files go in them.  In general, the default for these options is expressed in
terms of `${prefix}', so that specifying just `--prefix' will affect all of the
other directory specifications that were not explicitly provided.

The most portable way to affect installation locations is to pass the correct
locations to `configure'; however, many packages provide one or both of the
following shortcuts of passing variable assignments to the `make install'
command line to change installation locations without having to reconfigure or
recompile.

The first method involves providing an override variable for each affected
directory.  For example, `make install prefix=/alternate/directory' will choose
an alternate location for all directory configuration variables that were
expressed in terms of `${prefix}'.  Any directories that were specified during
`configure', but not in terms of `${prefix}', must each be overridden at install
time for the entire installation to be relocated.  The approach of makefile
variable overrides for each directory variable is required by the GNU Coding
Standards, and ideally causes no recompilation.  However, some platforms have
known limitations with the semantics of shared libraries that end up requiring
recompilation when using this method, particularly noticeable in packages that
use GNU Libtool.

The second method involves providing the `DESTDIR' variable.  For example, `make
install DESTDIR=/alternate/directory' will prepend `/alternate/directory' before
all installation names.  The approach of `DESTDIR' overrides is not required by
the GNU Coding Standards, and does not work on platforms that have drive
letters.  On the other hand, it does better at avoiding recompilation issues,
and works well even when some directory options were not specified in terms of
`${prefix}' at `configure' time.

Optional Features
=================

This package offers the ability to configure how verbose the execution of `make'
will be.  For these packages, running `./configure --enable-silent-rules' sets
the default to minimal output, which can be overridden with `make V=1'; while
running `./configure --disable-silent-rules' sets the default to verbose, which
can be overridden with `make V=0'.

Particular systems
==================

On HP-UX, the default C compiler is not ANSI C compatible.  If GNU CC is not
installed, it is recommended to use the following options in order to use an
ANSI C compiler:

     ./configure CC="cc -Ae -D_XOPEN_SOURCE=500"

and if that doesn't work, install pre-built binaries of GCC for HP-UX.

HP-UX `make' updates targets which have the same time stamps as their
prerequisites, which makes it generally unusable when shipped generated files
such as `configure' are involved.  Use GNU `make' instead.

On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot parse its
`<wchar.h>' header file.  The option `-nodtk' can be used as a workaround.  If
GNU CC is not installed, it is therefore recommended to try

     ./configure CC="cc"

and if that doesn't work, try

     ./configure CC="cc -nodtk"

On Solaris, don't put `/usr/ucb' early in your `PATH'.  This directory contains
several dysfunctional programs; working variants of these programs are available
in `/usr/bin'.  So, if you need `/usr/ucb' in your `PATH', put it _after_
`/usr/bin'.

On Haiku, software installed for all users goes in `/boot/common', not
`/usr/local'.  It is recommended to use the following options:

     ./configure --prefix=/boot/common

Specifying the System Type
==========================

There may be some features `configure' cannot figure out automatically, but
needs to determine by the type of machine the package will run on.  Usually,
assuming the package is built to be run on the _same_ architectures, `configure'
can figure that out, but if it prints a message saying it cannot guess the
machine type, give it the `--build=TYPE' option.  TYPE can either be a short
name for the system type, such as `sun4', or a canonical name which has the
form:

     CPU-COMPANY-SYSTEM

where SYSTEM can have one of these forms:

     OS
     KERNEL-OS

See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't need to
know the machine type.

If you are _building_ compiler tools for cross-compiling, you should use the
option `--target=TYPE' to select the type of system they will produce code for.

If you want to _use_ a cross compiler, that generates code for a platform
different from the build platform, you should specify the "host" platform (i.e.,
that on which the generated programs will eventually be run) with `--host=TYPE'.

Sharing Defaults
================

If you want to set default values for `configure' scripts to share, you can
create a site shell script called `config.site' that gives default values for
variables like `CC', `cache_file', and `prefix'.  `configure' looks for
`PREFIX/share/config.site' if it exists, then `PREFIX/etc/config.site' if it
exists.  Or, you can set the `CONFIG_SITE' environment variable to the location
of the site script.  A warning: not all `configure' scripts look for a site
script.

Defining Variables
==================

Variables not defined in a site shell script can be set in the environment
passed to `configure'.  However, some packages may run configure again during
the build, and the customized values of these variables may be lost.  In order
to avoid this problem, you should set them in the `configure' command line,
using `VAR=value'.  For example:

     ./configure CC=/usr/local2/bin/gcc

causes the specified `gcc' to be used as the C compiler (unless it is
overridden in the site shell script).

Unfortunately, this technique does not work for `CONFIG_SHELL' due to
an Autoconf bug.  Until the bug is fixed you can use this workaround:

     CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash

`configure' Invocation
======================

`configure' recognizes the following options to control how it operates.

`--help'
`-h'
     Print a summary of all of the options to `configure', and exit.

`--help=short'
`--help=recursive'
     Print a summary of the options unique to this package's
     `configure', and exit.  The `short' variant lists options used
     only in the top level, while the `recursive' variant lists options
     also present in any nested packages.

`--version'
`-V'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`--cache-file=FILE'
     Enable the cache: use and save the results of the tests in FILE,
     traditionally `config.cache'.  FILE defaults to `/dev/null' to
     disable caching.

`--config-cache'
`-C'
     Alias for `--cache-file=config.cache'.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`--prefix=DIR'
     Use DIR as the installation prefix.  *note Installation Names::
     for more details, including other options available for fine-tuning
     the installation locations.

`--no-create'
`-n'
     Run the configure checks, but stop before creating any output
     files.

`configure' also accepts some other, not widely useful, options.  Run
`configure --help' for more details.