This closes #2529

artemis-native/README

@@ -1,46 +0,0 @@
-
-This is a simple tutorial on compiling libActiveMQLibAIO.so
-
-DEPENDENCIES
-
-Make sure you install these packages:
-
-- G++ (yum install gcc-c++ or aptitude install g++)
-- Gcc (yum insall gcc or aptitude install gcc)
-- JDK (full JDK)
-
-
-LIBAIO INFORMATION
-
-libaio is part of the kernel project. The library makes system calls on the kernel layer.
-
-This is the project information:
-
-Git Repository:  git://git.kernel.org/pub/scm/libs/libaio/libaio.git
-Mailing List:    linux-aio@kvack.org
-
-
-STEPS TO BUILD
-
-1. Make sure you have JAVA_HOME defined, and pointing to the root of your JDK:
-
-Example:
-
- $> export JAVA_HOME=/usr/share/jdk1.7
-
-
-2. Call compile-native.sh. Bootstrap will call all the initial scripts you need
- $>  ./compile-native.sh
-
-if you are missing any dependencies, autoconf would tell you what you're missing.
-
-
-COMPILED FILE
-
-The produced file will be under the ./target/nar (example: ./target/nar/artemis-native-1.0.0-amd64-Linux-gpp-jni/lib/amd64-Linux-gpp/jni/libartemis-native-1.0.0.so)
-and you will have to rename it manually under ./bin following the appropriate pattern.
-
-
-DOCUMENTATION
-
-The User Manual, chapter 38 (Libaio Native Libraries) will provide more details about our native libraries on libaio.

artemis-native/README.md

@@ -0,0 +1,87 @@
+# Introduction
+
+
+This is a simple tutorial about building and packaging the libartemis-native library. The libartemis-native is a thin
+layer library that interface with Linux' lib AIO library as part of the journaling feature of the broker when operating
+with AIO journal.
+
+The lib AIO is a Linux-specific dependency, therefore having a relatively modern Linux operating system is assumed for
+the purpose of this documentation.
+
+## Dependencies
+
+In order to build the package, make sure you install these packages:
+
+- The GNU compiler library container both the C and C++ compiler
+- The GNU C library
+- The respective libaio package for your Linux distribution
+- JDK (full JDK)
+
+
+For example, on Fedora Linux, compilation of the library requires the following specific packages:
+
+- glibc-devel
+- libaio-devel
+- gcc
+- gcc-g++
+- java-1.8.0-openjdk-devel
+
+### Cross compilation
+
+Using a 64-bit Linux OS, it is possible to cross-compile the 32-bit version of the library. For this, the 32-bits
+version of the GNU C Library and lib AIO should be installed.
+
+Once again using Fedora Linux as an example, it would mean that the following packages need to be installed:
+
+- glibc-devel.i686
+- libaio-devel.i686
+
+## Lib AIO Information
+
+The Lib AIO is the Linux' Kernel Asynchronous I/O Support Library. It is part of the kernel project. The library makes
+system calls on the kernel layer.
+
+This is the project information:
+
+Git Repository:  git://git.kernel.org/pub/scm/libs/libaio/libaio.git
+Mailing List:    linux-aio@kvack.org
+
+
+## Steps to build
+
+1. Make sure you have JAVA_HOME defined, and pointing to the root of your JDK:
+
+Example:
+
+```export JAVA_HOME=/usr/share/jdk1.7```
+
+
+2. Call compile-native.sh. Bootstrap will call all the initial scripts you need
+ $>  ./compile-native.sh
+
+if you are missing any dependencies, autoconf would tell you what you're missing.
+
+
+### Compiled File
+
+The produced file will be under the ./target/nar (example: ./target/nar/artemis-native-1.0.0-amd64-Linux-gpp-jni/lib/amd64-Linux-gpp/jni/libartemis-native-1.0.0.so)
+and you will have to rename it manually under ./bin following the appropriate pattern.
+
+### Advanced Compilation Methods and Developer-specific Documentation
+
+Passing additional options to the compiler:
+```cmake -DCMAKE_USER_C_FLAGS="-fomit-frame-pointer" -DCMAKE_VERBOSE_MAKEFILE=On .```
+
+Compiling with debug options:
+```cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_VERBOSE_MAKEFILE=On .```
+
+Cross-compilation:
+```cmake -DCMAKE_VERBOSE_MAKEFILE=On -DCMAKE_USER_C_FLAGS="-m32" -DARTEMIS_CROSS_COMPILE=On -DARTEMIS_CROSS_COMPILE_ROOT_PATH=/usr/lib .```
+
+Cross-compilation with debugging symbols:
+```cmake -DCMAKE_VERBOSE_MAKEFILE=On -DCMAKE_USER_C_FLAGS="-m32" -DARTEMIS_CROSS_COMPILE=On -DARTEMIS_CROSS_COMPILE_ROOT_PATH=/usr/lib .```
+
+
+## Lib AIO Documentation
+
+The User Manual, chapter 38 (Libaio Native Libraries) will provide more details about our native libraries on libaio.

artemis-native/src/main/c/CMakeLists.txt

@@ -28,13 +28,37 @@ if (JNI_FOUND)
     message (STATUS "JNI_LIBRARIES=${JNI_LIBRARIES}")
 endif()
 
-# you may want to remove this next line for debugging
+# You may want to adjust this next line for debugging. The -O3 is removed by default, since it would make debugging
-# -O3 would make inline debug hard
+# harder. Nonetheless, it can still be added by passing CMAKE_USER_C_FLAGS
-#ADD_DEFINITIONS("-O3 -Wall -z execstack")
+# Also note that define the C99 as the minimum supported standard so the code can be compiled with older GCC versions
-ADD_DEFINITIONS("-O3 -Wall")
+# (circa 4.4)
-#ADD_DEFINITIONS("-fdump-tree-all -Wall -pg -g")
+set(CMAKE_C_FLAGS_DEBUG "-Wall -std=c99 -z execstack -fdump-tree-all -Wall -pg -g ${CMAKE_USER_C_FLAGS}")
+set(CMAKE_C_FLAGS "-O3 -std=c99 -Wall ${CMAKE_USER_C_FLAGS}")
 
-find_library(LIBAIO NAMES aio)
+
+set(ARTEMIS_LIB_NAME artemis-native-64)
+if (CMAKE_SIZEOF_VOID_P EQUAL 4)
+    set(ARTEMIS_LIB_NAME artemis-native-32)
+endif()
+
+set(ARTEMIS_CROSS_COMPILE OFF CACHE BOOL "Cross-compile the native library")
+
+if (ARTEMIS_CROSS_COMPILE)
+    if (CMAKE_SIZEOF_VOID_P EQUAL 4)
+        message(FATAL_ERROR "Cannot cross-compile to 32-bit architecture in a 32-bit architecture")
+    endif()
+
+    message(STATUS "Using cross-compilation")
+    set(ARTEMIS_CROSS_COMPILE_ROOT_PATH /usr/lib)
+    set(ARTEMIS_LIB_NAME artemis-native-32)
+
+    # The Cmake variable CMAKE_FIND_ROOT_PATH cannot be set via CLI, so we have to use a separate variable and then
+    # set it to that value. We use ARTEMIS_CROSS_COMPILE_ROOT_PATH for that.
+    set(CMAKE_FIND_ROOT_PATH ${ARTEMIS_CROSS_COMPILE_ROOT_PATH})
+endif()
+
+find_library(LIBAIO_LIB NAMES aio)
+message(STATUS "Using the following libaio library for linking: ${LIBAIO_LIB}")
 
 INCLUDE_DIRECTORIES(. ${JNI_INCLUDE_DIRS})
 
@@ -46,20 +70,9 @@ ADD_CUSTOM_COMMAND(
 
 ADD_LIBRARY(artemis-native SHARED org_apache_activemq_artemis_jlibaio_LibaioContext.c org_apache_activemq_artemis_jlibaio_LibaioContext.h exception_helper.h)
 
-target_link_libraries(artemis-native aio)
+target_link_libraries(artemis-native ${LIBAIO_LIB})
 
 set_target_properties(artemis-native PROPERTIES
-         LIBRARY_OUTPUT_DIRECTORY ../../../bin)
-
-# It is weird but this is how you are supposed to validate between 32 and 64 bits architecture
-if (CMAKE_SIZEOF_VOID_P EQUAL 8)
-    set_target_properties(artemis-native PROPERTIES
               LIBRARY_OUTPUT_DIRECTORY ../../../bin
-             LIBRARY_OUTPUT_NAME artemis-native-64)
+              LIBRARY_OUTPUT_NAME ${ARTEMIS_LIB_NAME})
-   message("-- Setting up library as artemis-native-64 based on current architecture")
+message(STATUS "Setting up library as ${ARTEMIS_LIB_NAME} based on current architecture")
-else()
-    set_target_properties(artemis-native PROPERTIES
-             LIBRARY_OUTPUT_DIRECTORY ../../../bin
-             LIBRARY_OUTPUT_NAME artemis-native-32)
-   message("-- Setting up library as artemis-native-32 based on current architecture")
-endif()