This is a text help for DIET installation, extracted from the User's Manual. 



                                 Dependencies



General remarks on DIET platform dependencies

   DIET is itself written in C and C++. DIET is based on CORBA and thus
   depends on the chosen CORBA implementation.
   Additionally, some of DIET extensions make a strong use of libraries
   themselves written in C and C++.
   Thus, we could expect DIET to be available on any platform offering
   decent version of such compilers.

   DIET undergoes daily regression tests 
   (see \url{http://graal.ens-lyon.fr/DietDashboard}) on various hardwares,
   a couple of Un*x based operating systems (under different distributions),
   MacOSX and AIX, and mainly with GCC.
   But, thanks to users reports (punctual deployments and special tests
   conduced before every release), DIET is known to be usable on a large
   range of platforms.

   Nevertheless, if you encounter installation difficulties don't hesitate
   to post on DIET's users mailing list: \verb+diet-usr@listes.ens-lyon.fr+
   (for the archives refer to 
   \url{http://graal.ens-lyon.fr/DIET/mail-lists.html}).

   If you find a bug in DIET, please don't hesitate to submit a bug report on
   \url{http://graal.ens-lyon.fr/bugzilla}. If you have multiple bugs
   to report, please make multiple submissions, rather than submitting
   multiple bugs in a single report.

Hardware dependencies

   DIET is fully tested on Linux/i386 and Linux/i686 platforms. DIET is known
   to work on Linux/Sparc, Linux/i64, Linux/amd64, Linux/Alpha, 
   Linux/PowerPC AIX/powerPC and MacOS/PowerPC platforms. At some point
   in DIET history, DIET used to be tested on the Solaris/Sparc platforms ...

Supported Compilers

   DIET is supported on GCC with versions ranging from 3.2.X to 4.6.X. Note 
   that due to omniORB 4 requirements towards thread-safe management of
   exception handling, compiling DIET with gcc requires at least gcc-2.96.

Operating System dependencies

   DIET is fully tested on Linux [with varying distributions like Debian,
   Red Hat Enterprise Linux (RHEL 5.x onwards), Fedora Core (5)],
    on AIX (5.3) and on MacOSX (Darwin 8).

Software dependencies

   CORBA is used for all communications inside the platform.
   The implementations of CORBA currently supported in DIET is omniORB 4.1
   which itself depends on Python.

   NB: We have noticed that some problems occur with Python 2.3: the C++ 
   code generated by idl could not be compiled. It has been patched in DIET,
   but some warnings may still appear.

   omniORB 4.1 itself also depends on OpenSSL in case you wish to secure 
   your DIET platform. If you want to deploy a secure DIET platform, SSL
   support is not yet implemented  in DIET, but an easy way to do so is to 
   deploy DIET over a VPN.

   In order to deploy CORBA services with omniORB, a configuration file
   and a log directory are required for a complete description of the 
   services. Their paths can be given to omniORB either at runtime 
   (through the well-known environment variables $OMNIORB_CONFIG and
   $OMNINAMES_LOGDIR), and/or at omniORB compile time (with the
   --with-omniORB-config and --with-omniNames-logdir options).

   Some examples provided in the DIET sources depend on the BLAS
   and scalapack libraries. However the compilation of those BLAS and
   scalapack dependent examples are optional.



                             Compiling the platform



   DIET compilation process moved away from the traditional autotools way of
   things to a tool named cmake (mainly to benefit from cmake's built-in
   regression tests mechanism).

   Before compiling DIET itself, first install the above mentioned dependencies.
   Then untar the DIET archive and change current directory to its root 
   directory.

Obtaining and installing cmake per se

   DIET requires using cmake at least version 2.6.x. Most *nix distributions
   comes with cmake pre-installed or is available in their repositories.
   Still, you might need to install an up-to-date version cmake's official site 
   distributes many binary versions (alas packaged as tarballs) which are made
   available at http://www.cmake.org/HTML/Download.html.
   Optionally, you can download the sources and recompile them: this simple
   process (./bootstrap; make; make install) is described at 
   http://www.cmake.org/HTML/Install.html.

Configuring DIET's compilation: cmake quick instruction

   If you are already experienced with cmake then using it to compile DIET 
   should provide no surprise. 
   DIET respects cmake's best practices e.g. by clearly separating the source
   tree from the binary tree (or compile tree), by exposing the main configuration
   optional flag variables prefixed with DIET_ (and by hiding away the technical
   variables) and by not postponing configuration difficulties (in particular
   the handling of external dependencies like libraries) to compile stage.

   Cmake classically provides two ways for setting configuration parameters in 
   order to generate the makefiles in the form of two commands ccmake and cmake
   (the first one has an extra "c" character):

   -- ccmake [options] <path-to-source> 
   in order to specify the parameters interactively through a GUI interface

   -- cmake [options] <path-to-source> [-D<var>:<type>=<value>]
   in order to define the parameters with the -D flag directly from the command line.

   In the above syntax description of both commands, <path-to-source> specifies 
   a path to the top level of the source tree (i.e. the directory where the top 
   level CMakeLists.txt file is to be encountered). Also the current working 
   directory will be used as the root of the build tree for the project (out of
   source building is generally encouraged especially when working on a CVS tree).

   Here is a short list of cmake internal parameters that are worth mentioning:
   
   -- CMAKE_BUILD_TYPE controls the type of build mode among which Debug will 
   produce binaries and libraries with the debugging information

   -- CMAKE_VERBOSE_MAKEFILE is a Boolean parameter which when set to ON will 
   generate makefiles without the .SILENT directive. This is useful for watching 
   the invoked commands and their arguments in case things go wrong.

   -- CMAKE_C[XX]_FLAGS* is a family of parameters used for the setting and the 
   customization of various C/C++ compiler options.

   -- CMAKE_INSTALL_PREFIX variable defines the location of the install directory
   (defaulted to /usr/local on un*x). This is cmake's portable equivalent of the 
   autotools configure's --prefix= option.

   Eventually, here is a short list of ccmake interface tips:

   --  when lost, look at the bottom lines of the interface which always 
   summarizes ccmake's most pertinent options (corresponding keyboard shortcuts) 
   depending on your current context

   -- hitting the "h" key will direct you ccmake embedded tutorial and a list of 
   keyboard shortcuts (as mentioned in the bottom lines, hit "e" to exit)

   -- up/down navigation among parameter items can be achieved with the up/down 
   arrows

   -- when on a parameter item, the line in inverted colors (close above the 
   bottom of the screen) contains a short description of the selected parameter 
   as well as the set of possible/recommended values

   -- toggling of boolean parameters is made with enter
   
   -- press enter to edit path variables

   -- when editing a PATH typed parameter the TAB keyboard shortcut provides an
   emacs-like (or bash-like) automatic path completion.

   -- toggling of advanced mode (press "t") reveals hidden parameters

A ccmake walk-through for the impatients

   Assume that DIET_HOME represents a path to the top level directory of 
   DIET sources. This DIET sources directories tree can be obtained by DIET 
   users by expanding the DIET current source level distribution tarball.
   But for the DIET developers this directories tree simply corresponds to
   the git clone of the DIET sources hierarchy.

   Additionally, assume we created a build tree directory and cd to it (in the 
   example below we chose DIET_HOME/Bin as build tree, but feel free to 
   follow your conventions):


   -- cd DIET_HOME/Bin

   -- ccmake .. to enter the GUI

   -- press c (equivalent of bootstrap.sh of the autotools)

   -- toggle the desired options e.g. DIET_BUILD_EXAMPLES. 

   -- specify the CMAKE_INSTALL_PREFIX parameter (if you wish to install in a 
   directory different from /usr/local,

   -- press c again, for checking required dependencies check all the parameters 
   preceded with the * (star) character whose value was automatically retrieved 
   by cmake.

   -- provide the required information i.e. fill in the proper values for all 
   parameters whose value is terminated by NOT-FOUND

   -- iterate the above process of parameter checking, toggle/specification and
   configuration until all configuration information is satisfied 


   -- press g to generate the makefile 

   -- press q to exit ccmake

   -- make in order to classically launch the compilation process

   -- make install when installation is required

DIET's main configuration flags

   Here are the main configuration flags:

   -- OMNIORB4_DIR is the path to the omniORB4 installation directory (only 
   relevant when omniORB4 was not installed in /usr/local).

   Example: cmake .. -DOMNIORB4_DIR:PATH=$HOME/local/omniORB-4.1.5

   -- DIET_BUILD_EXAMPLES enables the compilation of a set of general 
   client/server examples. Note that some specific examples (e.g. 
   DIET_BUILD_BLAS_EXAMPLES) require some additional flag to be activated too.

   -- DIET_BUILD_LIBRARIES which is enabled by default, enables the compilation
   of the DIET libraries. Disabling this option is only useful if you wish to 
   restrict the compilation to the construction of the documentation.

DIET's extensions configuration flags

   DIET has many extensions (some of them are still) experimental. These
   extensions most often rely on external packages that need to be pre-installed.
   One should notice that some of those extensions offer concurrent 
   functionalities.
   This explains the usage of configuration flags in order to obtain the 
   compilation of the desired extensions.

   -- DIET_USE_TOOLS enables the build of DIET diagnostic tools

   -- DIET_USE_ALT_BATCH enables DIET support of Appleseeds (refer to 
   \url{http://grail.sdsc.edu/projects/appleseeds/}) based batch extensions.

   -- DIET_BUILD_BLAS_EXAMPLES option enables the compilation of the BLAS 
   based DIET examples, as a sub-module of examples.
   The BLAS (http://www.netlib.org/blas/) (Basic Linear Algebra Subprograms)
   are high quality ``building block'' routines for performing basic vector and 
   matrix operations.
   Level 1 BLAS do vector-vector operations, Level 2 BLAS do matrix-vector
   operations, and Level 3 BLAS do matrix-matrix operations.
   Because the BLAS are efficient, portable, and widely available, they're 
   commonly used in the development of high quality linear algebra software.
   DIET uses BLAS to build demonstration examples of client/server.
   Note that the option DIET_BUILD_BLAS_EXAMPLES can only be effective when 
   DIET_BUILD_EXAMPLES is enabled. DIET_BUILD_BLAS_EXAMPLES is disabled by
   default.

   -- DIET_WITH_MULTI_MA enables the so called MULTI Master Agent support 
   which allows the user to connect several MA for them to act as bounded.
   When this option is activated, such a bounded MA is allowed to search for a 
   SeD into the MA hierarchies it is connected to.
   Note that MULTI-Master-Agent support is based on the CORBA layer which is to 
   be opposed with DIET_USE_JXTA which offers similar functionalities but based 
   on JXTA.
   
   -- DIET_USE_CCS enables client custom scheduling
   
   -- DIET_USE_CLOUD enables cloud support (supported: Amazon EC2/Eucalyptus)

   -- DIET_USE_LOG enables LogService logging extension

   -- DIET_USE_USERSCHED enables user scheduler extension

   -- DIET_USE_WORKFLOW enables the support of workflow.

   -- DIET_WITH_STATISTICS enables the generation of statistics logs

DIET's advanced configuration flags

   Eventually, some configuration flags control the general result of the
   compilation or some developers extensions:

   -- BUILD_TESTING is a conventional variable (which is not a cmake internal 
   variable) which specifies that the regression tests should also be compiled.

   -- BUILD_SHARED_LIBS is a cmake internal variable which specifies whether 
   the libraries should be dynamics as opposed to static

   -- Maintainer By default cmake offers four different build modes that one 
   toggles by positioning CMAKE_BUILD_TYPE built-in variable (to Debug, 
   Release, RelWithDebInfo and MinSizeRel).
   Maintainer is an additional mode which fulfills two basic needs of the 
   task of the maintainer of Diet.
   The first preventive task is to provide code free from any compilation and 
   link warnings.
   The second corresponds to the snafu stage which is to debug the code.
   For reaching those goals the Maintainer build type sets the compilers flags, 
   respectively the linker flags, with all the possible warning flags activated, 
   resp. with the additional debug flags.



                             Compiling and installing



Summarizing the configuration choices

   Once the configuration is properly made one can check the choices made
   by looking the little summary proposed by cmake.
   This summary should look like ([...] denotes eluded portions):

   ~/DIET > ./cmake ..
   [...]
    - Install prefix: /home/diet/local/diet
    - OmniORB found: YES
      * OmniORB directory: /home/diet/local/omniORB-4.1.5
      * OmniORB includes: /home/diet/local/omniORB-4.1.5/include
      * OmniORB libraries: /home/diet/local/omniORB-4.1.5/lib/libomniDynamic4.so;
	[...]libomniORB4.so;[...]libomnithread.so;[...]libCOS4.so;[...]
    - General options:
      * Documentation: ON
      * Dynamics Libraries: ON
      * Examples: ON
      * BLAS Examples: ON
    - Options set:
      * Batch: ON
      * Client scheduling: ON
      * Statistics: ON

   [...]

   A more complete, yet technical, way of making sure is to check the content
   of the file named CMakeCache.txt (generated by cmake in the directory 
   from which cmake was invocated).
   When exchanging with the developers list it is a recommendable practice
   to join the content of this file which summarizes your options and also
   the automatic package/library detections made by cmake.

Compiling stage

   You are now done with the configuration stage (equivalent of both the
   bootstrap.sh and ./configure stage of the autotools).
   You are now back to your platform level development tools i.e. +make
   when working on Unices.
   Hence you can now proceed with the compiling process by launching make.

Testing

   If you configured DIET with the BUILD_TESTING you can easily run
   the regression tests by invoking the make test.
   This is equivalent to invoking ctest command (ctest is part of cmake
   package). ctest --help provides a summary of the advanced options of 
   ctest among which we recommend the --verbose option.

Creating packages
   You can easily create packages using CMake and CPack. For this, when running
   ccmake, select one or multiple of the following CPack generators:
    - CPACK_BINARY_DRAGNDROP    # OK, but not really interesting 
    - CPACK_BINARY_PACKAGEMAKER # OK
    - CPACK_BINARY_STGZ         # OK
    - CPACK_BINARY_TBZ2         # OK
    - CPACK_BINARY_TGZ          # OK
    - CPACK_BINARY_NSIS         # not tested yet
    - CPACK_BINARY_DEB          # do not use, it does not generate proper debian packages
    - CPACK_BINARY_RPM          # do not use, it does not generate proper rpm packages
    - CPACK_BINARY_OSXX11       # do not use, creates a .app, but it does not mean much for us
    - CPACK_BINARY_BUNDLE       # currently not supported
    - CPACK_SOURCE_TBZ2         # currently not supported
    - CPACK_SOURCE_TGZ          # currently not supported
    - CPACK_SOURCE_TZ           # currently not supported
    - CPACK_SOURCE_ZIP          # currently not supported




                             Diet client/server examples



   A set of various examples of DIET server/client are provided within
   the DIET archive:
   
   -- file_transfer: the server computes the sizes of two input files and 
   returns them. A third output parameter may be returned; the server 
   decides randomly whether to send back the first file. This is to show 
   how to manage a variable number of arguments: the profile declares all 
   arguments that may be filled, even if they might not be all filled at 
   each request/computation.

   -- dmat_manips: the server offers matrix manipulation routines: 
   transposition (T), product (MatPROD), sum (MatSUM, SqMatSUM for 
   square matrices), and   SqMatSUM_opt for square matrices but re-using 
   the memory space of the second operand for the result). Any subset of 
   these operations can be specified on the command line. The last two of
   them are given for compatibility with a BLAS server as explained below.
  
   -- BLAS: the server offers the dgemm BLAS functionality.  We plan to 
   offer all BLAS (Basic Linear Algebraic Subroutines) in the future. 
   Since this function computes C = alpha AB + beta C, it can also compute 
   a matrix-matrix product, a sum of square matrices, etc. All these	   
   services are offered by the BLAS server. Two clients are designed to 
   use these services: one (dgemm_client.c) is designed to use the dgemm_
   function only, and the other one (client.c) to use all BLAS functions 
   (but currently only dgemm_) and sub-services, such as MatPROD.
  
   -- scalapack: the server is designed to offer all scalapack (parallel 
   version of the LAPACK library) functions but only manages the pdgemm_
   function so far. The pdgemm_ routine is the parallel version of the dgemm_
   function, so that the server also offers all the same sub-services. Two 
   clients are designed to use these services: one (pdgemm_client.c) is 
   designed to use the pdgemm_ function only, and the other one (client.c) 
   to use all scalapack functions and sub-services, such as MatPROD.

   -- workflow: The programs in this directory are examples that demonstrate 
   how to use the workflow feature of diet. The files representing the 
   workflows that can be tested are stored in xml sub-directory.
   For each workflow, you can fin the required services in the corresponding
   xml file (check the path attribute of each node element).
   For the scalar manipulation example, you can use scalar\_server that 
   gathers four different elementary services.

Compiling the examples

   Cmake will set the examples to be compiled when setting the 
   DIET_BUILD_EXAMPLES to ON which can be achieved by toggling the corresponding 
   entry of ccmake GUI's or by adding -DDIET_BUILD_EXAMPLES:BOOL=ON to the 
   command line arguments of [c]cmake invocation.
   Note that this option is disabled by default.

   The compilation of the examples, respectively the installation, is executed 
   on the above described invocation of make, resp. make install stages.
   The binary of the examples are placed in the <install_dir>/bin/examples
   sub-directory of the installation sirectory.
   
   Likewise, the samples of configuration files located in src/examples/cfgs
   are processed by make install to create ready-to-use configuration files 
   in src/examples/cfgs and then copied into <install_dir>/etc/cfgs.
