Merge pull request #126 from ComputationalRadiationPhysics/topic-release1.2

Topic release1.2

Author: ax3l

.travis.yml

@@ -10,7 +10,6 @@ compiler:
 
 env:
   global:
-    - SPLASH_ROOT=~/lib/splash
     - BUILD=~/buildTmp
     - SRC=$TRAVIS_BUILD_DIR
   matrix:
@@ -21,8 +20,10 @@ env:
 script:
   - cd $BUILD
 # compile libSplash and install
-  - cmake -DTOOLS_MPI=$SPLASHMPI -DCMAKE_INSTALL_PREFIX=~/lib/splash $SRC
-  - make install
+  - cmake -DTOOLS_MPI=$SPLASHMPI $SRC
+  - make package
+  - sudo dpkg -i libsplash*.deb
+  - ls -hal /usr/share/pyshared/
   - rm -rf $BUILD/*
 # compile examples/
   - cmake -DWITH_MPI=$SPLASHMPI $SRC/examples

CHANGELOG.md

@@ -1,6 +1,35 @@
 Change Log for libSplash
 ================================================================
 
+Release 1.2.0
+-------------
+**Date:** 2014-04-30
+
+**New Features**
+
+ - splash2xdmf python script to create XDMF descriptions for libSplash files
+   with domain information
+ - allow to read/write attributes at groups
+
+
+**Interface Changes**
+
+ - major interface change: simplified interfaces as most read/write routines
+   now use a Selection class for describe the source layout
+ - local domain offsets are now exclusive, i.e. do not include the
+   global domain offset
+ - changed file format version to 2.0
+ - add a finalize() call to ParallelDataCollector to free MPI resources
+
+
+**Bug Fixes**
+
+ - fix automatic chunking algorithm
+ - only use HDF5 hyperslaps if necessary for improved performance
+ - fix bug in getMaxID and getEntryIDs for ParallelDataCollector
+
+
+
 Release 1.1.1
 -------------
 **Date:** 2014-02-20

CMakeLists.txt

@@ -1,13 +1,14 @@
  #
- # Copyright 2013 Felix Schmitt, Axel Huebl
+ # Copyright 2013-2014 Felix Schmitt, Axel Huebl
  #
  # This file is part of libSplash. 
  # 
  # libSplash is free software: you can redistribute it and/or modify 
  # it under the terms of of either the GNU General Public License or 
  # the GNU Lesser General Public License as published by 
  # the Free Software Foundation, either version 3 of the License, or 
- # (at your option) any later version. 
+ # (at your option) any later version.
+ #
  # libSplash is distributed in the hope that it will be useful, 
  # but WITHOUT ANY WARRANTY; without even the implied warranty of 
  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
@@ -198,6 +199,10 @@ ELSE(HDF5_IS_PARALLEL)
         )
 ENDIF(HDF5_IS_PARALLEL)
 
+# install python scripts
+INSTALL(FILES ${CMAKE_CURRENT_SOURCE_DIR}/tools/splash2xdmf.py
+        DESTINATION share/pyshared)
+
 #-------------------------------------------------------------------------------
 
 # build tools
@@ -239,8 +244,131 @@ IF(WITH_TOOLS)
 
     #install tools
     INSTALL(TARGETS splashtools RUNTIME DESTINATION bin)
+    INSTALL(FILES ${CMAKE_CURRENT_SOURCE_DIR}/tools/splash2xdmf.py DESTINATION bin)
 ENDIF(WITH_TOOLS)
 
+#-------------------------------------------------------------------------------
+
+# Packaging
+# Reference for variables: http://www.cmake.org/Wiki/CMake:CPackConfiguration
+
+SET(CPACK_GENERATOR "DEB;TGZ;TBZ2;ZIP")
+
+SET(CPACK_PACKAGE_NAME "libsplash") # lower case required (debian policy)
+SET(CPACK_PACKAGE_DESCRIPTION_SUMMARY
+    "Simple Parallel file output Library for Accumulating Simulation data using Hdf5")
+SET(CPACK_PACKAGE_DESCRIPTION_FILE "${CMAKE_CURRENT_SOURCE_DIR}/README.md")
+SET(CPACK_RESOURCE_FILE_README "${CMAKE_CURRENT_SOURCE_DIR}/README.md")
+SET(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/COPYING")
+# a valid email is required - happy spamming :)
+SET(CPACK_PACKAGE_CONTACT "Felix Schmitt <felix.schmitt@zih.tu-dresden.de>")
+SET(CPACK_PACKAGE_VENDOR "ZIH and HZDR")
+# CPACK_PACKAGING_INSTALL_PREFIX : default is "/usr" for deb and rpm
+
+SET(CPACK_PACKAGE_VERSION_MAJOR "${SPLASH_VERSION_MAJOR}")
+SET(CPACK_PACKAGE_VERSION_MINOR "${SPLASH_VERSION_MINOR}")
+SET(CPACK_PACKAGE_VERSION_PATCH "${SPLASH_VERSION_PATCH}")
+SET(CPACK_PACKAGE_VERSION
+    "${SPLASH_VERSION_MAJOR}.${SPLASH_VERSION_MINOR}.${SPLASH_VERSION_PATCH}")
+
+# from `dpkg --print-architecture`
+IF(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64" OR
+   CMAKE_SYSTEM_PROCESSOR STREQUAL "amd64")
+  SET(SPLASH_ARCHITECTURE "amd64")
+ELSE()
+  SET(SPLASH_ARCHITECTURE "i386")
+ENDIF()
+
+# probably only required by NSIS
+SET(CPACK_PACKAGE_INSTALL_DIRECTORY "CMake ${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}")
+
+# ship (strip) all found executables
+SET(CPACK_STRIP_FILES ON)
+# do not ship source files (packed in a weird absolute dir)
+SET(CPACK_SOURCE_STRIP_FILES OFF)
+#SET(CPACK_PACKAGE_EXECUTABLES "MyExecutable" "My Executable") # only required by NSIS
+
+# try to detect used MPI flavor
+SET(MPI_FLAVOR "FLAVOR-NOTFOUND")
+IF(HDF5_IS_PARALLEL OR TOOLS_MPI)
+  SET(MPI_FLAVOR "openmpi")
+  SET(MPI_FLAVOR_BIN "openmpi-bin")
+  SET(MPI_FLAVOR_MINVERSION 1.5.1)
+  STRING(FIND "${MPI_C_LIBRARIES}" "libmpich" MPI_FLAVOR_POS)
+  IF(${MPI_FLAVOR_POS} GREATER -1)
+    SET(MPI_FLAVOR "mpich2")
+    SET(MPI_FLAVOR_BIN "mpich2")
+    SET(MPI_FLAVOR_MINVERSION 1.4.1)
+  ENDIF(${MPI_FLAVOR_POS} GREATER -1)
+ENDIF(HDF5_IS_PARALLEL OR TOOLS_MPI)
+
+# package name containing all necessary information for feature identification
+# inspect .deb meta data (like version) with dpkg --info <package>.deb
+IF(NOT HDF5_IS_PARALLEL)
+  SET(SPLASH_PACKAGE_EXTRA_PREFIX "-serial")
+ENDIF(NOT HDF5_IS_PARALLEL)
+IF(MPI_FLAVOR)
+  SET(SPLASH_PACKAGE_EXTRA_PREFIX
+      "${SPLASH_PACKAGE_EXTRA_PREFIX}-${MPI_FLAVOR}")
+ENDIF(MPI_FLAVOR)
+IF(NOT SPLASH_RELEASE)
+  SET(SPLASH_PACKAGE_DEBUG "-dbg")
+ENDIF(NOT SPLASH_RELEASE)
+
+SET(CPACK_PACKAGE_FILE_NAME
+    "${CPACK_PACKAGE_NAME}${SPLASH_PACKAGE_EXTRA_PREFIX}-${SPLASH_ARCHITECTURE}${SPLASH_PACKAGE_DEBUG}"
+   )
+
+# DEB specific ----------------------------------------------------------------
+#   package relation policy at
+#   http://www.debian.org/doc/debian-policy/ch-relationships.html
+
+# default values that are already set in a fine and noble manner
+# CPACK_DEBIAN_PACKAGE_MAINTAINER <- CPACK_PACKAGE_CONTACT
+# CPACK_DEBIAN_PACKAGE_NAME <- CPACK_PACKAGE_NAME
+# CPACK_DEBIAN_PACKAGE_VERSION <- CPACK_PACKAGE_VERSION
+# CPACK_DEBIAN_PACKAGE_DESCRIPTION <- CPACK_PACKAGE_DESCRIPTION_SUMMARY
+# CPACK_DEBIAN_PACKAGE_SECTION : default is "devel"
+# CPACK_DEBIAN_PACKAGE_PRIORITY : default is "optional"
+# CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA : pos/pre inst/rm scripts
+
+# from `dpkg --print-architecture`
+SET(CPACK_DEBIAN_PACKAGE_ARCHITECTURE "${SPLASH_ARCHITECTURE}") # default is i386
+
+# the dev packages are a little bit too much, but since there is a lack of
+# convenient named meta packages we use them to trigger the dependencies
+IF(HDF5_IS_PARALLEL)
+  SET(CPACK_DEBIAN_PACKAGE_DEPENDS
+      "libhdf5-${MPI_FLAVOR}-dev (>= 1.8.6)"
+     )
+  SET(CPACK_DEBIAN_PACKAGE_RECOMMENDS
+      "${MPI_FLAVOR_BIN} (>= ${MPI_FLAVOR_MINVERSION})"
+     )
+ELSE(HDF5_IS_PARALLEL)
+  SET(CPACK_DEBIAN_PACKAGE_DEPENDS
+      "libhdf5-serial-dev (>= 1.8.6)"
+     )
+  IF(TOOLS_MPI)	
+    SET(CPACK_DEBIAN_PACKAGE_DEPENDS
+        "${CPACK_DEBIAN_PACKAGE_DEPENDS}, lib${MPI_FLAVOR}-dev (>= ${MPI_FLAVOR_MINVERSION})"
+       )
+    SET(CPACK_DEBIAN_PACKAGE_RECOMMENDS
+        "${MPI_FLAVOR_BIN} (>= ${MPI_FLAVOR_MINVERSION})"
+       )
+  ENDIF(TOOLS_MPI)
+ENDIF(HDF5_IS_PARALLEL)
+
+# CPACK_DEBIAN_PACKAGE_SUGGESTS
+# deb-src support
+# DEBIAN_PACKAGE_BUILDS_DEPENDS : not implemented by cmake yet
+
+# END: DEB specific -----------------------------------------------------------
 
+# create or creates specific library names
+#  libsplash.so     -> libsplash.so.1
+#  libsplash.so.1   -> libsplash.so.1.1
+#  libsplash.so.1.1 -> libsplash.so.1.1.0
 
+# has to be included after all vars are set
+INCLUDE(CPack)
 

doc/INSTALL.md

@@ -25,39 +25,80 @@ Compiling
 ---------
 
 To **compile libSplash**, it is recommended to create a new build folder and execute
-`$ cmake -DCMAKE_INSTALL_PREFIX=<INSTALL PATH> <CMakeLists.txt-PATH>`
+```bash
+cmake -DCMAKE_INSTALL_PREFIX=<INSTALL PATH> <CMakeLists.txt-PATH>
+```
 
 Than run `$ make install` to build and install libSplash library and binaries to the chosen
 installation directory. This will build libSplash as an shared object library (libsplash.so)
 as well as all tools.
 
 If you do not want to build splashtools, pass `-DWITH_TOOLS=OFF` to your cmake command.
-To enable MPI parallel splashtools, pass `-DTOOLS_MPI=ON` to your cmake command.
+To disable MPI parallel splashtools, pass `-DTOOLS_MPI=OFF` to your cmake command.
 
 By default, the RELEASE version is built. To create libSplash with DEBUG symbols,
 pass `-DSPLASH_RELEASE=OFF` to your cmake command.
 To see verbose internal (!) HDF5 debug output, pass `-DDEBUG_VERBOSE=ON`
 to your cmake command line.
 
-Afterwards, please add `<INSTALL PATH>/bin` to your `$PATH` environment variable and
-`<INSTALL PATH>/lib` to your `$LD_LIBRARY_PATH`.
-Setting an additional environment variable `export SPLASH_ROOT=<INSTALL PATH>` will
-help finding the installed libraries with CMake scripts.
+Afterwards, configure your environment variables:
+```bash
+# helps finding the installed library, e.g. with CMake scripts
+export SPLASH_ROOT=<INSTALL PATH>
+# provides command line access to our tools
+export PATH=$SPLASH_ROOT/bin:$PATH
+# path for the linker
+export LD_LIBRARY_PATH=$SPLASH_ROOT/lib:$LD_LIBRARY_PATH
+# provides our python modules, e.g. for xdmf creation
+export PYTHONPATH=$SPLASH_ROOT/bin:$PYTHONPATH
+```
 
 
-Linking
--------
+Linking to your Project
+-----------------------
 
 To use libSplash in your project, you must link against the created shared object library
 libsplash.so or against the statically linked archive libsplash.a.
 
 Because we are linking to HDF5, the following **external dependencies** must be linked:
-- `-lhdf5`
-- `-lpthread`
-- `-lz`
-- `-lrt`
-- `-ldl`
-- `-lm`
+- `-lhdf5`, `-lpthread`, `-lz`, `-lrt`, `-ldl`, `-lm`
+
+If you are using CMake you can download our `FindSplash.cmake` module with
+```bash
+wget https://raw.githubusercontent.com/ComputationalRadiationPhysics/picongpu/dev/src/cmake/FindSplash.cmake
+# read the documentation
+cmake -DCMAKE_MODULE_PATH=. --help-module FindSplash | less
+```
+
+and use the following lines in your `CMakeLists.txt`:
+```cmake
+# this example will require at least CMake 2.8.5
+cmake_minimum_required(VERSION 2.8.5)
+
+# add path to FindSplash.cmake, e.g. in the directory in cmake/
+set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${CMAKE_CURRENT_SOURCE_DIR}/cmake/)
+
+# find libSplash installation
+#   optional: prefer static libraries over shared ones (but do not force them)
+set(Splash_USE_STATIC_LIBS ON)
+
+#   optional: specifiy (minimal) version, require Splash and specific components, e.g.
+#           (Splash 1.1.1 REQUIRED COMPONENTS PARALLEL)
+find_package(Splash)
+
+if(Splash_FOUND)
+  # where to find headers (-I includes for compiler)
+  include_directories(SYSTEM ${Splash_INCLUDE_DIRS})
+  # additional compiler flags (-DFOO=bar)
+  add_definitions(${Splash_DEFINITIONS})
+  # libraries to link against
+  set(LIBS ${LIBS} ${Splash_LIBRARIES})
+endif(Splash_FOUND)
+
+# add_executable(yourBinary ${SOURCES})
+# ...
+# target_link_libraries(yourBinary ${LIBS})
+```
 
 Tests
 -----