Build and Installation Instructions for OpenVSP


INTRODUCTION

  OpenVSP is a parametric aircraft geometry tool.  OpenVSP allows the
  user to create a 3D model of an aircraft defined by common engineering
  parameters.  This model can be processed into formats suitable for
  engineering analysis.

  This code comes from a development branch, targeting future version 3.

  The predecessors to OpenVSP have been developed by JR Gloudemans and
  others for NASA since the early 1990's.  In January 2012, OpenVSP was
  released as an open source project under the NOSA 1.3 license.  The
  first open source version was 2.0.0.

LICENSE

  OpenVSP is available under the terms of the NASA Open Source Agreement
  (NOSA) version 1.3.  The complete terms of the license are specified
  in the LICENSE file.

STATE OF THE CODE

  This fork focuses on rearchitecting the code along two lines:
  - Porting to Qt Widgets from FLTK.
  - Making the internals simpler to use and develop with.

  The Qt porting effort is carried out on OS X 10.9 using Qt 5.3.
  The event loop of FLTK and Qt is merged. Although the code should
  work on all plaforms supported by both Qt and FLTK, it is not
  tested but on OS X.

  Eventually, once the parameter bindings are well integrated with Qt
  code, it should be ported to QML. Given the hard dependency on OpenGL
  for the GUI, QML is a logical step forward. So far, Qt Widgets have the
  smallest impedance mismatch with FLTK. Lot of code is being trivially
  ported.

  A simple tool was developed and is used to convert the FLUID ui descriptions
  to Qt. It's called fl2ui and is available from https://github.com/KubaO/fl2ui.git
  This takes some drudgery out of the conversion process - saves copy-pasting
  a lot of strings, and offers widgets that are often ready for inclusion into
  layouts.

  The Qt port is undertaken by Kuba Ober, kuba at (sea of showers) dot org
  The parenthesized phrase is to be translated into Latin and concatenated to
  a single word. It is a selenological feature.

ROADMAP EXCERPTS

  Short-term porting plan is:

  1. Port the main window. This is the lowest hanging fruit at the moment.

  2. Reimplement the GroupLayout along with porting remaining GuiDevices and screens.

  Mid-term, some modularization work is envisioned, with interfaces and ability to have
  a number of objects implementing a given interface all being seen by the interface
  consumer (e.g. we'd have IGeom, IGeomUi).

  Long-term, the minimum required version of Qt will be 5.4. This is because:

  1. The OpenGL implementation is runtime selectable in 5.4. On Windows, a modern
  OpenGL ES 2 implementation that runs on top of DirectX is provided through ANGLE.

  2. The QOpenGLWidget seems to be the way forward, esp. for interop with QML.

  The targeted OpenGL will have to be ES 2.0, since that's what's available on mobile
  devices, and mobile devices are our target. ANGLE implements OpenGL ES only.
  Since ANGLE gives a modern OpenGL ES on top of modern DirectX - the users
  won't have to worry about needing an OpenGL driver. Even though Qt is intelligent
  in its choice of a driver (a higher-level native driver will win over ANGLE),
  a power user can always override the selection through a commandline argument,
  handled by the Qt library itself.

  Since Qt 5.4 targets WinRT, we can then support Metro, er, Modern on both Desktop
  and Mobile Windows.

DEPENDENCIES

  OpenVSP relies on a variety of libraries and code made available by
  other authors.  If you are a VSP user, you probably don't need to
  worry about this.  Take this section as informational, providing
  credit where due.

  If you wish to compile VSP or to use the VSP API, then you will need
  to know more.  These dependencies fall into four categories: those
  assumed to be provided by the operating system; those that must be
  downloaded and installed by the developer; those that are bundled
  with OpenVSP, but the developer may want to use a different version
  installed on the system; and those that are bundled with OpenVSP.

  Most users are familiar with the OpenVSP GUI.  OpenVSP can also be
  accessed by other programs via an API, or in a batch mode with no
  user interaction.  These 'headless' targets may be compiled without
  any of the graphics libraries installed.  Although most developers
  will want to build the graphical version, those dependencies only
  needed by the GUI program and graphics-enabled API are marked
  GRAPHICS_ONLY.

  1) Assumed provided by the operating system.

  -OpenGL (www.opengl.org) 3D graphics library.  OpenGL should be
   available on any platform capable of displaying 3D graphics.
   GRAPHICS_ONLY

  2) Installed by the developer.

  -C++ Compiler.  OpenVSP requires a modern C++ compiler that supports
   some C++11 features.  We try to support popular free compilers on the
   main platforms.  For Windows, we require Visual Studio 2010 Express
   or newer.  For Mac OSX or Linux/BSD, we support LLVM and GCC.

  -CMake 3 (www.cmake.org) Cross-platform build system.  CMake
   generates platform-native build files which control compilation of
   OpenVSP.  CMake is available as a standard package on most Linux
   systems and binary installers are available for many other platforms
   including Windows and Mac OS X.

   Note: There is a temporary dependency on CMake 3. Long-term it is
   planned to support CMake 2.8.

  -SWIG (www.swig.org) Simplified Wrapper and Interface Generator.
   Optional dependency used to build interface to API for Python
   and other scripting languages.

  -Python (www.python.org) Scripting language.  Optional dependency
   required if building the Python API module.

  -Doxygen (www.doxygen.org) Documentation generator.  Optional
   dependency used for generating documentation from the source.  Can
   also utilize graphviz dot to generate improved figures in the
   documentation. (www.graphviz.org)

   The current man-made documentation is next to nonexistent, so
   all you can reasonably expect is doxygen's machine-generated content.

  -Qt 5.3 or newer (www.qt-project.org) An application development framework.

  3) Bundled with OpenVSP, but system libraries may substitute.

  -Code-Eli (github.com/ddmarshall/Code-Eli) Curve & surface library.
   Code-Eli was developed by David Marshall to meet OpenVSP's needs.
   It is a header-only library that must be available to build.  It is
   not likely to be packaged on any system.

  -Eigen3 (eigen.tuxfamily.org) Template library for linear algebra.
   This header-only library is required by Code-Eli.  Eigen3 is likely
   to be available as a standard package on Linux.

  -AngelScript (www.angelcode.com/angelscript) Embedded scripting
   language for C++.  Used for user-defined components.

  -CppTest (cpptest.sourceforge.net) C++ Unit testing framework.

  -Libxml2 (www.xmlsoft.org) XML parser and toolkit.  Libxml2 most
   likely comes pre-installed with most Linux distributions and 
   Mac OS X systems.  Windows users must download the source and
   build this library following the Libxml2 instructions.

  -CMinpack (http://devernay.free.fr/hacks/cminpack/) C/C++ port of
   standard Fortran Levenberg-Marquardt implementation.

  -GLM (glm.g-truc.net) OpenGL math library.  GRAPHICS_ONLY

  The requirements below are only necessary until the completion of
  Qt port, and thus are short-term.

  -FLTK (www.fltk.org) Cross-platform windowing library.  FLTK should
   be available as a standard package on most Linux systems and can
   be installed from source on Windows and Mac OS X according to the
   FLTK instructions.  GRAPHICS_ONLY

  -libjpeg (www.ijg.org) JPEG compression library.  We typically
   piggy-back on the libjpeg accompanying FLTK.  If you prefer to use
   your own, it is typically pre-installed on Linux.  You will need
   to build it yourself for MacOS or Windows.  GRAPHICS_ONLY

  -GLEW (glew.sourceforge.net) OpenGL Extension Wrangler Library.  This
   library is used to access any modern OpenGL features.  GRAPHICS_ONLY

  4) Bundled with OpenVSP.

  -STEPcode (stepcode.org) Library for working with STEP standard
   files.  Based on an old library developed by NIST.  This is a
   relatively new library, in constant development.  Not likely
   to be packaged on any system.

  -nanoflann (code.google.com/p/nanoflann) Fast nearest neighbors
   library.

  -sixseries NASA 6-Series airfoil generation Fortran code released
   to the public domain from NASA TM X 3069 September, 1974.
   Converted to C using F2C.

  -Triangle by Jonathan Shewchuk (www.cs.cmu.edu/~quake/triangle.html)
   2D Delaunay triangulator.  This routine has been included in
   this distribution.

  -triInt by Tomas Moller Fast triangle-triangle intersection test.
   This code comes from two sources previously available online.
   When JGT was taken over by Taylor and Francis, the source
   accompanying the articles became unavailable.  The routines are
   included in this distribution.

   Old URL:
     jgt.akpeters.com/papers/Moller97/tritri.html
     jgt.akpeters.com/papers/MollerTrumbore97/code.html

   Tomas Möller, Ben Trumbore, "Fast, Minimum Storage Ray-Triangle
     Intersection", Journal of Graphics Tools, Vol. 2, Iss. 1, 1997.

   Tomas Möller, "A Fast Triangle-Triangle Intersection Test", Journal
     of Graphics Tools, Vol. 2, Iss. 2, 1997.

  -glFont2 by Brad Fish (students.cs.byu.edu/~bfish/glfont2.php)
   2D OpenGL font tool.  glFont2 has been included in this source
   distribution.  GRAPHICS_ONLY

BUILD INSTRUCTIONS

   All of the supporting libraries and code described above in
   DEPENDENCIES categories 1 and 2 must be properly installed.
   Those in categories 3 and 4 can be satisfied by OpenVSP itself.
   Any dependencies from category 3 that the developer prefers
   to use a system library must be properly installed.

   We only expect two common cases where developers would prefer
   to use the system libraries over the bundled ones.  First, on
   Linux where system libraries are readily available and
   distributions strongly prefer they are used.  Second, when a
   developer is simultaneously working on OpenVSP and the
   dependency in question.

   OpenVSP is packaged for compilation into three CMake projects:
   the main OpenVSP project with all the OpenVSP source and the
   category 4 dependencies; a Libraries project with all the
   category 3 dependencies; a SuperProject that can unify building
   the other two projects.

   Casual developers new to OpenVSP will want to use the
   SuperProject; building it should take care of everything.  More
   involved developers will want to use the OpenVSP and Libraries
   projects directly; the OpenVSP project integrates better than
   the SuperProject with most IDEs.  Developers who want to use
   only system libraries for the category 3 dependencies have no
   need for the Libraries project; they can work only with the
   main project.

   CMake is used to construct the build files for a project.  CMake
   supports out-of-tree builds which keep the source tree free
   of generated files.  Create a build directory to contain the
   generated files, say 'openvsp/build'.  Then, change to the
   build directory and run CMake - passing a relative path to
   'openvsp/src', say 'cmake ../src'.

   Once CMake has generated the files for your favorite build
   system, load them in the IDE and compile or launch the build
   from the command line.

   The OpenVSP CMake system can be configured by defining a
   handful of variables.  These variables may be relevant to some
   or all of the projects.

   All project variables:

    VSP_NO_GRAPHICS -- Set this variable to disable everything
     to do with graphics.  The build system will not search for
     or build any graphics libraries.  It will only build the
     headless batch-mode VSP, API, and bindings.  This is ideal
     for building VSP on a HPC machine with limited access.

   OpenVSP project variables:

    VSP_LIBRARY_PATH -- Set this variable to point at the
     directory where the Libraries project was built.  The
     SuperProject sets this path automatically.  The Libraries
     project writes a file 'VSP_Libraries_Config.cmake'
     containing numerous settings to this path.

    XXXX_INSTALL_DIR -- Set this variable to point to a
     directory where a library has been installed.  This provides
     a suggestion to a corresponding FIND_PACKAGE( XXXX ).  Do
     not use these variables with VSP_LIBRARY_PATH, it will
     overwrite them.  Acceptable versions of this variable are:

      FLTK_INSTALL_DIR
      CPPTEST_INSTALL_DIR
      LIBXML2_INSTALL_DIR
      GLM_INSTALL_DIR
      GLEW_INSTALL_DIR
      EIGEN_INSTALL_DIR
      CODEELI_INSTALL_DIR
      CMINPACK_INSTALL_DIR

   Libraries & SuperProject project variables:

    VSP_USE_SYSTEM_XXXX -- Set this variable to search for the
     particular library rather than use the bundled versions.
     Acceptable versions of this variable are:

      VSP_USE_SYSTEM_CPPTEST
      VSP_USE_SYSTEM_LIBXML2
      VSP_USE_SYSTEM_EIGEN
      VSP_USE_SYSTEM_CODEELI
      VSP_USE_SYSTEM_FLTK
      VSP_USE_SYSTEM_GLM
      VSP_USE_SYSTEM_GLEW
      VSP_USE_SYSTEM_CMINPACK

DEBIAN PACKAGES

   If you wish to use system libraries to satisfy the category 3
   libraries on a Debian system, you will need to install the
   following packages.

   Development environment:

    git
    git-gui
    cmake
    g++

   Libraries:

    libcpptest-dev
    libxml2-dev
    libfltk1.3-dev
    libeigen3-dev
    libglm-dev
    libglew-dev
    libjpeg-dev

   Optional packages:

    python-dev
    swig
    doxygen
    graphviz


   On Mint, users have also found that they must install the following package:

    fluid