INSTALLATION

This library is known to work on Ubuntu 24.04 using g++ 14.2.0, but it will
likely work with other configurations, too.  Lines starting with "$" are bash
commands.

1. Unzip the package into a directory called PhysBAM.  For the purposes of these
instructions, we will assume this is located at /home/user/PhysBAM.

2. Set your environment.

$ export PHYSBAM="/home/user/PhysBAM" # Point to your directory.
$ export PROJ="$PHYSBAM"/Projects
$ export PUBLIC="$PHYSBAM"/Public_Library
$ export PHYSBAM_DATA_DIRECTORY="$PHYSBAM"/Public_Data
$ export PHYSBAM_COMPILE_COUNT=4
$ export DEFAULT_ARCH=nocona
$ export PLATFORM=nocona

3. Set up our compilation command.  We will make an alias for it for convenience, but you could run it directly.

$ alias cs='nice scons --warn=no-duplicate-environment --warn=no-deprecated -Q --implicit-cache -u -j $PHYSBAM_COMPILE_COUNT'

4. Install dependencies.

$ sudo apt-get install scons cblas g++ scons libpng12-dev libjpeg62-dev
$ sudo apt-get install libavformat-dev libavcodec-dev libavutil-dev libglut3-dev freeglut3-dev bison flex

5. Move to your PhysBAM directory.

$ cd $PHYSBAM

6. Fetch Public_Data.

$ wget https://www.cs.ucr.edu/~craigs/papers/physbam/Public_Data.zip
$ unzip Public_Data.zip

7. The library is built using the Scons tool.  Next we need to configure the
build, which is done using the SConstruct.options file.  This sets some default
configuration options.  Most compilation issues that you run into can be
corrected by changing this file or the build script (SConstruct) directly.  This
may be needed if you need to use a specific compiler or handle non-standard
install locations.  This file is also used to enable or disable features in the
library.  This reduces dependencies but also functionality.  The default
settings provide a reasonable compromise for most uses.

8. Build the library.  We will use the alias we made to do this:

$ cs

You can also compile in debug mode by running the command

$ cs TYPE=debug

Notes on building: you may encounter issues with files containing "LEX" and
"YACC" in their names.  Alternatively, you may encounter linker errors with
names like "yyparse" or "yy_delete_buffer."  These are mostly related to scons
not correctly understanding the dependency structure of the build.  The solution
is to compile with "cs -k" to tell SCons to keep going, even past the original
build problem, allowing it to build the necessary dependencies.  Simply
rerunning the build command will cause the build to succeed.  This problem is
only encountered on a fresh build; subsequent builds should work correctly since
the generated dependencies will already exist.

9. Go to the project directory of interest; these are located in the Project
directory.  In this case, we will do a rigid body test.

$ cd Projects/rigid_bodies

10. Run a test (or a script containing many tests)

$ ./rigid_bodies 1

The simulation output is placed in a directory, this can normally be set from
the commandline via the -o flag.  Otherwise, there will be a default value that
can generally be deduced by reading the output.  In this case, the output is
located in Standard_Tests/Test_1.

11. You can view the test using the provided viewer.

$ $PHYSBAM/Projects/qt_viewer/qt_viewer Standard_Tests/Test_1


