Merge pull request #58 from ComputationalRadiationPhysics/dev

Merging lasting changes about versioning and splitting server and library code

Author: theZiz

CMakeLists.txt

@@ -89,45 +89,6 @@ be built yourself nevertheless or the distribution versions are outdated.
         `-DBoost_DIR=$BOOST/install`, where `$BOOST` is
         the path of the boost_1_56_0 directory.
 
-### Requirements for the server only
-
-* __libwebsockets__ for the connection between server and an HTML5 client.
-  It is in steady development and the most recent version should be used:
-  * _From Source_:
-    * `git clone https://github.com/warmcat/libwebsockets.git`
-    * `cd libwebsockets`
-    * `mkdir build`
-    * With admin rights and no other version of libwebsockets installed:
-      * `cd build`
-      * `cmake ..`
-        * `cmake ..` may fail if OpenSSL is not available. ISAAC itself does
-          not support HTTPS connections at the moment anyway, thus it can be
-          disabled with: `cmake -DLWS_WITH_SSL=OFF ..`
-      * `make`
-      * `sudo make install`
-    * Otherwise:
-      * `mkdir install`
-      * `cd build`
-      * `cmake -DCMAKE_INSTALL_PREFIX=../install ..`
-        * `cmake -DCMAKE_INSTALL_PREFIX=../install ..` may fail if OpenSSL
-          is not available. ISAAC itself does not support HTTPS connections at
-          the moment anyway, thus it can be disabled with:
-          `cmake -DLWS_WITH_SSL=OFF -DCMAKE_INSTALL_PREFIX=../install ..`
-      * `make install`
-      * Now a local version of libwebsockets is installed in the install
-        directory in the libwebsockets root folder. Later while compiling the
-        ISAAC server using libwebsockets add
-        `-DLibwebsockets_DIR=$LIBWEBSOCKETS/install/lib/cmake/libwebsockets`, where
-        `$LIBWEBSOCKETS` is the root folder of the libwebsockets source (the directory
-        `git clone …` created).
-* __gStreamer__ is only needed, if streaming over RTP or the Twitch plugin shall
-  be used. It should be possible to build gStreamer yourself, but it
-  is strongly adviced - even from the gStreamer team themself - to use
-  the prebuilt version of your distribution. The HML5 Client can show
-  streams of a server without gStreamer.
-  * _Debian/Ubuntu_:
-    * `sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base0.10-dev libgstreamer-plugins-good1.0-dev libgstreamer-plugins-bad1.0-dev`
-
 ### Requirements for the in situ library and the examples using it
 
 The ISAACConfig.cmake searches for these requirements. See
@@ -202,23 +163,96 @@ The ISAACConfig.cmake searches for these requirements. See
         MPI (including the ISAAC examples) add `$MPI/install` to the
         CMake variable `CMAKE_MODULE_PATH` to use this version.
 
+### Requirements for the server only
+
+* __libwebsockets__ for the connection between server and an HTML5 client.
+  It is in steady development and the most recent version should be used:
+  * _From Source_:
+    * `git clone https://github.com/warmcat/libwebsockets.git`
+    * `cd libwebsockets`
+    * `mkdir build`
+    * With admin rights and no other version of libwebsockets installed:
+      * `cd build`
+      * `cmake ..`
+        * `cmake ..` may fail if OpenSSL is not available. ISAAC itself does
+          not support HTTPS connections at the moment anyway, thus it can be
+          disabled with: `cmake -DLWS_WITH_SSL=OFF ..`
+      * `make`
+      * `sudo make install`
+    * Otherwise:
+      * `mkdir install`
+      * `cd build`
+      * `cmake -DCMAKE_INSTALL_PREFIX=../install ..`
+        * `cmake -DCMAKE_INSTALL_PREFIX=../install ..` may fail if OpenSSL
+          is not available. ISAAC itself does not support HTTPS connections at
+          the moment anyway, thus it can be disabled with:
+          `cmake -DLWS_WITH_SSL=OFF -DCMAKE_INSTALL_PREFIX=../install ..`
+      * `make install`
+      * Now a local version of libwebsockets is installed in the install
+        directory in the libwebsockets root folder. Later while compiling the
+        ISAAC server using libwebsockets add
+        `-DLibwebsockets_DIR=$LIBWEBSOCKETS/install/lib/cmake/libwebsockets`, where
+        `$LIBWEBSOCKETS` is the root folder of the libwebsockets source (the directory
+        `git clone …` created).
+* __gStreamer__ is only needed, if streaming over RTP or the Twitch plugin shall
+  be used. It should be possible to build gStreamer yourself, but it
+  is strongly adviced - even from the gStreamer team themself - to use
+  the prebuilt version of your distribution. The HML5 Client can show
+  streams of a server without gStreamer.
+  * _Debian/Ubuntu_:
+    * `sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base0.10-dev libgstreamer-plugins-good1.0-dev libgstreamer-plugins-bad1.0-dev`
+
 Building
 --------
 
-### The server
+### Installing the library
 
-The server uses CMake. Best practice is to create a new directory (like
-`build`) in the isaac root directory and change to it:
+To install the isaac library to use it in your project
+go to directory `lib` inside the isaac root folder, create a folder like
+`build` and do the classic cmake magic:
 
 * `git clone https://github.com/ComputationalRadiationPhysics/isaac.git`
 * `cd isaac`
+* `cd lib`
+* `mkdir build`
+* `cd build`
+* `cmake ..`
+* (`sudo`) ` make install`
+
+You don't need to call `make` before `make install` as the template library
+does not need to be built until compiling the using application.
+
+### The example
+
+The building of the examples works similar, but the root directory of
+the examples is the folder `example`, so after changing directory to
+isaac (`cd isaac`) do:
+
+* `cd example`
+* `mkdir build`
+* `cd build`
+* `cmake ..`
+  * Don't forget the maybe needed `-DLIB_DIR=…` parameters
+    needed for local installed libraries. E.g.
+    `cmake -DIceT_DIR=$ICET/install/lib ..`
+* `make`
+
+Afterwards you get the executables `example_cuda`, `example_alpaka` or both.
+For running these examples you need a running isaac server.
+
+### The server
+
+The server resides in the direcoty `server` and also uses CMake:
+
+* `cd isaac`
+* `cd server`
 * `mkdir build`
 * `cd build`
 * `cmake ..`
   * Don't forget the maybe needed `-DLIB_DIR=…` parameters
     needed for local installed libraries. E.g.
     `cmake -DLibwebsockets_DIR=$LIBWEBSOCKETS/install/lib/cmake/libwebsockets ..`
-  * There are some options to (de)activate features of ISAAC if they are not needed
+  * There are some options to (de)activate features of the server if they are not needed
     or not available on the system (like Gstreamer), which you can change with
     theese lines before `..` (in `cmake ..`) or afterwards with `ccmake` or `cmake-gui`:
     * `-DISAAC_GST=OFF` → Deactivates GStreamer.
@@ -232,7 +266,10 @@ The server uses CMake. Best practice is to create a new directory (like
     * `-DISAAC_ALPAKA=ON` → Activates ALPAKA. The used accelerator of Alpaka can be
       changed inside the file `example.cpp`. At default OpenMP version 2 is used as
       accelerator. At least CUDA or Alpaka need to be activated. 
-
+    * `-DISAAC_INSTALL_LIBRARY=OFF` → Does not install the library files while installing
+      the server. This may be wanted if library and server are not used on the same system.
+    * `-DISAAC_BUILD_SERVER=OFF` → Does not build nor install the server at all. Use this,
+      if you want to install the library on a system, but not the server itself.
 * `make`
 
 If you want to install the server type
@@ -245,29 +282,13 @@ Change the installation directory with adding
 
 in the initial `cmake ..`
 
-However, ISAAC doesn't need to be installed and can also directly be called with
+However, the server doesn't need to be installed and can also directly be called with
 
 * `./isaac`
 
 For more informations about parameters use `./isaac --help` or have
 a look in the __[server documentation](http://computationalradiationphysics.github.io/isaac/doc/server/index.html)__.
 
-### The example
-
-The building of the examples works similar, but the root directory of
-the examples is the folder `example`, so after changing directory to
-isaac (`cd isaac`) do:
-
-* `cd example`
-* `mkdir build`
-* `cd build`
-* `cmake ..` (Don't forget the maybe needed `-DLIB_DIR=…` parameters
-  needed for local installed libraries. E.g.
-  `cmake -DIceT_DIR=$ICET/install/lib ..`)
-* `make`
-
-Afterwards you get the executables `example_cuda`, `example_alpaka` or both.
-
 ### Testing
 
 To test the server and an example, just start the server with `./isaac`,
@@ -278,6 +299,28 @@ observable and steerable. You can run multiple instances of the example with
 `mpirun -c N ./example_KIND` with the number of instances `N` and `KIND`
 being `cuda` or `alpaka`. To exit the example, use the client or ctrl+C.
 
+### Versions
+
+ISAAC has three different more or less independent (!) version strings.
+The server and the library both have versions consisting of the
+
+* major version number which is increased if the API compatibility is
+  broken to older versions,
+* minor version number, which indicates new features, but does not break
+  code not using these new features, and
+* patch version number, which is mostly for small bug fixes, but does not
+  change much about the behaviour.
+
+These version numbers are important if you want to use the ISAAC library
+in your application or you want to extend the server with your own
+meta data or image connector.
+
+The last version string of isaac, the protocol version number, does only
+consists of two version numbers: major and minor. The major protocol
+version number must be the same for server and library. The minor version
+number my differ, but in that case not all features of the protocol may
+be used.
+
 
 How to use in an own application
 --------------------------------

INSTALL.md

@@ -9,7 +9,7 @@ set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${ISAAC_DIR})
 set(ALPAKA_ROOT "${CMAKE_CURRENT_LIST_DIR}/../../alpaka/" CACHE STRING  "The location of the alpaka library")
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${ALPAKA_ROOT}")
 
-find_package(ISAAC 0.1.0 REQUIRED)
+find_package(ISAAC 1.1.0 REQUIRED)
 
 set(ISAAC_DEFINITIONS ${ISAAC_DEFINITIONS} "-DISAAC_MAX_FUNCTORS=3")
 set(ISAAC_DEFINITIONS ${ISAAC_DEFINITIONS} "-DISAAC_FUNCTOR_POW_ENABLED=0")

documentation/tunnel_putty1.png

@@ -195,10 +195,10 @@ int main(int argc, char **argv)
 		DevHost devHost (alpaka::pltf::getDevByIdx<PltfHost>(0u));
 		Stream  stream  (devAcc);
 
-		const alpaka::Vec<SimDim, size_t> global_size(d[0]*VOLUME_X,d[1]*VOLUME_Y,d[2]*VOLUME_Z);
-		const alpaka::Vec<SimDim, size_t> local_size(size_t(VOLUME_X),size_t(VOLUME_Y),size_t(VOLUME_Z));
-		const alpaka::Vec<DatDim, size_t> data_size(size_t(VOLUME_X) * size_t(VOLUME_Y) * size_t(VOLUME_Z));
-		const alpaka::Vec<SimDim, size_t> position(p[0]*VOLUME_X,p[1]*VOLUME_Y,p[2]*VOLUME_Z);
+		const alpaka::vec::Vec<SimDim, size_t> global_size(d[0]*VOLUME_X,d[1]*VOLUME_Y,d[2]*VOLUME_Z);
+		const alpaka::vec::Vec<SimDim, size_t> local_size(size_t(VOLUME_X),size_t(VOLUME_Y),size_t(VOLUME_Z));
+		const alpaka::vec::Vec<DatDim, size_t> data_size(size_t(VOLUME_X) * size_t(VOLUME_Y) * size_t(VOLUME_Z));
+		const alpaka::vec::Vec<SimDim, size_t> position(p[0]*VOLUME_X,p[1]*VOLUME_Y,p[2]*VOLUME_Z);
 	#else //CUDA
 		//////////////////////////////////
 		// Cuda specific initialization //
@@ -299,7 +299,7 @@ int main(int argc, char **argv)
 		SimDim, //Dimension of the Simulation. In this case: 3D
 		SourceList, //The boost::fusion list of Source Types
 		#if ISAAC_ALPAKA == 1
-			alpaka::Vec<SimDim, size_t>, //Type of the 3D vectors used later
+			alpaka::vec::Vec<SimDim, size_t>, //Type of the 3D vectors used later
 		#else //CUDA
 			std::vector<size_t>, //Type of the 3D vectors used later
 		#endif

documentation/tunnel_putty2.png

@@ -67,7 +67,7 @@ void update_data(
 				alpaka::mem::view::getPtrNative(hostBuffer1)[pos][2] = intensity;
 				alpaka::mem::view::getPtrNative(hostBuffer2)[pos] =  (2.0f - l)*(2.0f - l) / 4.0f;
 			}
-	const alpaka::Vec<alpaka::dim::DimInt<1>, size_t> data_size(size_t(local_size[0]) * size_t(local_size[1]) * size_t(local_size[2]));
+	const alpaka::vec::Vec<alpaka::dim::DimInt<1>, size_t> data_size(size_t(local_size[0]) * size_t(local_size[1]) * size_t(local_size[2]));
 	alpaka::mem::view::copy(stream, deviceBuffer1, hostBuffer1, data_size);
 	alpaka::mem::view::copy(stream, deviceBuffer2, hostBuffer2, data_size);
 #else
@@ -254,7 +254,7 @@ void read_vtk_to_memory(
 	}
 
 #if ISAAC_ALPAKA == 1
-	const alpaka::Vec<alpaka::dim::DimInt<1>, size_t> data_size(size_t(local_size[0]) * size_t(local_size[1]) * size_t(local_size[2]));
+	const alpaka::vec::Vec<alpaka::dim::DimInt<1>, size_t> data_size(size_t(local_size[0]) * size_t(local_size[1]) * size_t(local_size[2]));
 	alpaka::mem::view::copy(stream, deviceBuffer2, hostBuffer2, data_size);
 #else
 	cudaMemcpy(deviceBuffer2, hostBuffer2, sizeof(float)*prod, cudaMemcpyHostToDevice);