INSTALLATION DIRECTIONS FOR DARWIN2K ==================================== Contents: Introduction 1. Required packages 2. Optional packages a. RTC (Real Time Communications) b. XML support c. LAPACK and BLAS for improved numerical stability 3. The build process a. Using the provided scripts (Irix, Linux, Solaris) b. Fast version c. Fuller explanation 4. Building from CVS 5. Basic Installation (generic autoconf/configure options) Compliers and Options Compiling for Multiple Architectures Installation Names Optional Features Specifying the System Type Sharing Defaults Operation Controls ---------------------------------------------------------------------- Introduction. Darwin2K is distributed as source code, not as binaries; thus, the first step in using Darwin2K is to compile it. Building Darwin2K should be a simple process once all the required packages are installed. Most configuration problems seem to be caused by version differences between installed packages. *** Please see the 'Installation Troubleshooting' section of the Darwin2K *** *** FAQ (in the darwin2k-docs directory) for answers to specific *** *** questions, and instructions on what to do if your problem isn't *** *** addressed. *** ---------------------------------------------------------------------- 1. REQUIRED PACKAGES -------------------- To build Darwin2K from a source distribution, you will need - a C++ compiler, and - lex and yacc (or flex/bison). Note that gcc/g++ 2.95 is fairly buggy; if you are running this (which is likely the case if you have an out-of-the-box RedHat 7.0 system), you should upgrade gcc and g++. To build the graphical interfaces for displaying robot configurations and animating simulations, you will need - XForms 0.88 or 0.89 (you'll need libXpm installed for 0.89; also, if you're installing XForms from an RPM, you may need both the xforms and xforms-devel RPMs) - OpenGL: GL and GLU libraries (www.opengl.org) or the Mesa 3-D graphics library (www.mesa3d.org) ---------------------------------------------------------------------- 2. OPTIONAL PACKAGES -------------------- 2a. RTC (Real Time Communications) ---------------------------------- To run the synthesizer in addition to the simulator, you'll need the RTC includes, libraries, and binaries from http://darwin2k.sourceforge.net/rtc The available RTC packages are: rtc-1.8-nosrc-irix62n32only.tar.gz - Irix 6.x, compiled w/ -mips4 -n32 rtc-1.8-nosrc-irix62only.tar.gz - Irix 6.x rtc-1.8-nosrc-linux24only.tar.gz - Linux w/ 2.4 kernel rtc-bin-1.6.tar.gz - Linux w/ 2.2 kernel, Irix 6.x rtc-1.8-nosrc-solaris55only.tar.gz - Solaris Download the appropriate package for the operating system(s) you're using and uncompress and unpack the tar file. You'll need to tell Darwin2K the location of your RTC installation later. IMPORTANT: If you use the rtc-bin-1.6.tar.gz file (to get linux22 support), then you will need to do the following: cd cd lib ln -s default This is to make sure Darwin2K's configure script uses the correct architecture, since the tar file contains both Linux 2.2 kernel and Irix 6.2 libraries. NOTE: if you're building for multiple architectures on the same filesystem, then you should install the RTC packages for each architecture in *different* directories. 2b. XML support --------------- To try the new XML configuration file format, you need - libpopt (the command-line option parser used by RPM) - libxml (www.xmlsoft.org) - glib (www.gtk.org) Uncompress the tarball and extract it. You will pass the location of the extracted sources to the configure script when you build Darwin2K. Currently I only have the libraries and binaries for Linux and Irix 6.2 (compiled & linked with -mips4 -n32). 2c. LAPACK and BLAS for improved numerical stability ---------------------------------------------------- I have yet to find a stable, self-contained, free, open-source implementation of SVD in C++, after having tried several (including NRiC, which isn't free). So, optionally, you can use the SVD routine in the LAPACK library. If you want to do this, you'll need to have LAPACK and BLAS installed. I've only done this under RedHat linux, in which case the procedure is simple: just install the lapack and blas RPMS (I use the RedHat 7.1 LAPACK rpm and 7.2 BLAS rpm). ---------------------------------------------------------------------- 3. THE BUILD PROCESS -------------------- The easiest way to configure and build Darwin2K is to use one of the sample scripts in the cfg-scripts directory, as detailed in section 3a. If you're feeling both daring and lucky, you can try the fast version in section 3b. Finally, section 3c gives more detailed instructions on what the various options do. ***NOTE: if you're having trouble getting things configured and you run one of the configure/autogen scripts multiple times, make sure you remove 'config.cache' (if it's not already in the script). If you don't do this, then whatever results are in config.cache will be used again! 3a. Using the provided scripts (Irix, Linux, Solaris) If you're using Irix, Linux, or Solaris, then it's easiest to start with one of the simple shell scripts in the 'cfg-scripts' directory. If you are building Darwin2K from the CVS sources, use the "-autogen" scripts; otherwise, use the "-configure" scripts. After selecting the appropriate script, follow the steps below. (Note that platform-instructions are provided within each script.) 1. Copy the script to the directory in which you'll be building Darwin2K. 2. Edit the paths for the source and installation directories (these are the ones that start with "/home/cleger" in the scripts. 3. Change the CC, CXX, CFLAGS, CXXFLAGS, and/or LDFLAGS as desired. The default values should work in most cases. 4. If you want or don't want to use RTC, GtkGL, or XML, change the lines as appropriate. 5. Run the script, e.g. "sh ./linux-configure" 6. Type "make install" 7. If all goes well, run /bin/d2k-demos 8. If all does not go well, check the TROUBLESHOOTING file. Several common problems (particularly relating to RTC, GL, and Xforms configuration) and their solutions are covered there. 3b. The Fast Version (for the daring) If you are building from a 'darwin2k*.tar.gz' source tarball, have RTC unpacked in directory , and want to install Darwin2K in , then simply type ./configure --srcdir=`pwd` --prefix= --with-rtc= make && make install /bin/d2k-demos Without RTC, the commands are: ./configure --srcdir=`pwd` --prefix= make && make install /bin/d2k-demos Add the flag --enable-xml to the configure script to build the XML file parsing support. 3c. The fuller explanation If you are building from a source distribution (e.g., a darwin2k*.tar.gz file), you should have a script named './configure' in your home directory. If you are building from the CVS repository, skip to the next section. You may either build Darwin2K in place in the source directory, or in a separate build directory (this is useful when building for multiple architectures from the same sources). If you are building outside the source directory, replace './configure' with '/configure' in the following directions. Make sure that '' is an *absolute* directory. First, decide where you want to install darwin2k. Typically, you will want to install it in your home directory, either in $HOME or something like $HOME/D2K. This path will be called '' in these instructions (use an *absolute*, not relative, path). Second, if you have any compiler, preprocessor, or linker options that need to be passed, see "Compliers and Options" in Section 4 for information on how to do that. Also, some common cases are noted below in Section 3c. If you have RTC unpacked in directory '' (an *absolute* path), type ./configure --srcdir=`pwd` --prefix= --with-rtc= This will generate the Makefiles for building Darwin2K. If you don't have RTC, then instead type ./configure --srcdir=`pwd` --prefix= --without-rtc If you do not want to build the graphics targets, you can add the option '--disable-xforms' to the command line. If you do not specify '--prefix', it will default to '/usr/local'. In this case, you'll probably need to be root in order for the programs and data to be installed. For more information about './configure', read the generic "Basic Installation" directions below or try './configure --help'. Once configure has generated the necessary Makefiles, run make && make install to build and install Darwin2K. To see some demonstrations of Darwin2K simulating different robot configurations, you can now run /bin/d2k-demos Some of the demos currently aren't working, but then, some are :) The broken ones (particularly the walker and free-flyer) will hopefully be fixed soon. ---------------------------------------------------------------------- 4. BUILDING FROM CVS ==================== If you are building from CVS, you will need the following GNU packages: - autoconf - automake - libtool If you don't have them, the 'autogen.sh' script will tell you what you need and where to get them. The 'autogen.sh' script builds the configure script and then runs it. Simply follow the directions from Section 2 above, but substituting 'srcdir= /autogen.sh' for '/configure'. Make sure that '' is an *absolute* directory. If you are using a C-shell like tcsh, use instead 'env srcdir= /autogen.sh' ---------------------------------------------------------------------- 5. Basic Installation (generic autoconf/configure options) ========================================================== These are generic installation instructions. 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 each directory of the package. It may also create one or more `.h' files containing system-dependent definitions. Finally, it creates a shell script `config.status' that you can run in the future to recreate the current configuration, a file `config.cache' that saves the results of its tests to speed up reconfiguring, and a file `config.log' containing compiler output (useful mainly for debugging `configure'). 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 at some point `config.cache' contains results you don't want to keep, you may remove or edit it. The file `configure.in' is used to create `configure' by a program called `autoconf'. You only need `configure.in' if you want to change it or regenerate `configure' using a newer version of `autoconf'. The simplest way to compile this package is: 1. `cd' to the directory containing the package's source code and type `./configure' to configure the package for your system. If you're using `csh' on an old version of System V, you might need to type `sh ./configure' instead to prevent `csh' from trying to execute `configure' itself. Running `configure' takes awhile. While running, it prints some messages telling which features it is checking for. 2. Type `make' to compile the package. 3. Optionally, type `make check' to run any self-tests that come with the package. 4. Type `make install' to install the programs and any data files and documentation. 5. You can remove the program binaries and 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. Compilers and Options ===================== Some systems require unusual options for compilation or linking that the `configure' script does not know about. You can give `configure' initial values for variables by setting them in the environment. Using a Bourne-compatible shell, you can do that on the command line like this: CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure Or on systems that have the `env' program, you can do it like this: env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure The C++ compiler can be specified by setting the CXX environment variable. 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 must use a version of `make' that supports the `VPATH' variable, such as 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 `..'. If you have to use a `make' that does not supports the `VPATH' variable, you have 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. Installation Names ================== By default, `make install' will install the package's files in `/usr/local/bin', `/usr/local/man', etc. You can specify an installation prefix other than `/usr/local' by giving `configure' the option `--prefix=PATH'. You can specify separate installation prefixes for architecture-specific files and architecture-independent files. If you give `configure' the option `--exec-prefix=PATH', the package will use PATH as the prefix for installing programs and libraries. Documentation and other data files will still use the regular prefix. In addition, if you use an unusual directory layout you can give options like `--bindir=PATH' 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. If the package supports it, you can cause programs to be installed with an extra prefix or suffix on their names by giving `configure' the option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. Optional Features ================= Some packages pay attention to `--enable-FEATURE' options to `configure', where FEATURE indicates an optional part of the package. They may also pay attention to `--with-PACKAGE' options, where PACKAGE is something like `gnu-as' or `x' (for the X Window System). The `README' should mention any `--enable-' and `--with-' options that the package recognizes. For packages that use the X Window System, `configure' can usually find the X include and library files automatically, but if it doesn't, you can use the `configure' options `--x-includes=DIR' and `--x-libraries=DIR' to specify their locations. Specifying the System Type ========================== There may be some features `configure' can not figure out automatically, but needs to determine by the type of host the package will run on. Usually `configure' can figure that out, but if it prints a message saying it can not guess the host type, give it the `--host=TYPE' option. TYPE can either be a short name for the system type, such as `sun4', or a canonical name with three fields: CPU-COMPANY-SYSTEM 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 host type. If you are building compiler tools for cross-compiling, you can also use the `--target=TYPE' option to select the type of system they will produce code for and the `--build=TYPE' option to select the type of system on which you are compiling the package. 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. Operation Controls ================== `configure' recognizes the following options to control how it operates. `--cache-file=FILE' Use and save the results of the tests in FILE instead of `./config.cache'. Set FILE to `/dev/null' to disable caching, for debugging `configure'. `--help' Print a summary of the options to `configure', and exit. `--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. `--version' Print the version of Autoconf used to generate the `configure' script, and exit. `configure' also accepts some other, not widely useful, options.