Improve install instructions, reduce configuration complexity (#27)

- Added install instructions for embedding the library in CMake without package manager - Made adjustments to CMakeLists.txt to make this kind of installation work.
cross-language-cpp · May 7, 2021 · 6a2f975 · 6a2f975
1 parent 35fdcac
commit 6a2f975
Show file tree

Hide file tree

Showing 7 changed files with 104 additions and 35 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -7,7 +7,7 @@ jobs:
     - uses: actions/checkout@v2
     - uses: asdf-vm/actions/install@v1
     - name: Configure cmake
-      run: cmake -S . -B build -DDJINNI_WITH_OBJC=ON -DDJINNI_STATIC_LIB=ON -G Xcode
+      run: cmake -S . -B build -DDJINNI_WITH_OBJC=ON -G Xcode
     - name: Build release
       run: cmake --build build --parallel $(sysctl -n hw.ncpu) --config Release
     - name: Run tests
@@ -39,7 +39,7 @@ jobs:
         python -m pip install --upgrade pip
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
     - name: Configure cmake
-      run: cmake -S . -B build -DDJINNI_WITH_PYTHON=ON -DDJINNI_STATIC_LIB=ON
+      run: cmake -S . -B build -DDJINNI_WITH_PYTHON=ON
     - name: Build release
       run: cmake --build build --parallel $(sysctl -n hw.ncpu) --config Release
     - name: Run tests
@@ -52,7 +52,7 @@ jobs:
     - uses: actions/checkout@v2
     - uses: asdf-vm/actions/install@v1
     - name: Configure cmake
-      run: cmake -S . -B build -DDJINNI_WITH_JNI=ON -DDJINNI_STATIC_LIB=ON
+      run: cmake -S . -B build -DDJINNI_WITH_JNI=ON
     - name: Build release
       run: cmake --build build --parallel $(nproc) --config Release
     - name: Run tests
@@ -77,7 +77,7 @@ jobs:
         $URL = 'https://github.com/cross-language-cpp/djinni-generator/releases/download/' + $VERSION + '/djinni.bat'
         Invoke-WebRequest -Uri $URL -OutFile djinni.bat
     - name: Configure cmake
-      run: cmake -S . -B build -DDJINNI_WITH_CPPCLI=ON -DDJINNI_STATIC_LIB=ON -DCMAKE_INSTALL_PREFIX=build/check_install_root -DDJINNI_EXECUTABLE="$(((Get-Location).Path) -replace "\\","/")/djinni.bat" -G "Visual Studio 16 2019"
+      run: cmake -S . -B build -DDJINNI_WITH_CPPCLI=ON -DCMAKE_INSTALL_PREFIX=build/check_install_root -DDJINNI_EXECUTABLE="$(((Get-Location).Path) -replace "\\","/")/djinni.bat" -G "Visual Studio 16 2019"
     - name: Install nuget dependencies
       working-directory: build/test-suite
       run: dotnet restore DjinniCppCliTest.csproj --runtime win-x64

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -49,12 +49,11 @@ set(SRC_CPPCLI
   "djinni/cppcli/WrapperCache.cpp"
 )
 
-option(DJINNI_STATIC_LIB "Build Djinni support library as a static library instead of dynamic (the default)." off)
-if(DJINNI_STATIC_LIB)
-  add_library(djinni_support_lib STATIC ${SRC_SHARED})
-else()
-  add_library(djinni_support_lib SHARED ${SRC_SHARED})
-endif()
+# set `DJINNI_LIBRARY_TYPE` to `STATIC` or `SHARED` to define the type of library.
+# If undefined, the type will be determined based on `BUILD_SHARED_LIBS`
+add_library(djinni_support_lib ${DJINNI_LIBRARY_TYPE} ${SRC_SHARED})
+add_library(djinni-support-lib::djinni-support-lib ALIAS djinni_support_lib)
+
 source_group("" FILES ${SRC_SHARED})
 
 set_target_properties(djinni_support_lib PROPERTIES
@@ -97,11 +96,7 @@ if(DJINNI_WITH_OBJC)
       ${CMAKE_INSTALL_INCLUDEDIR}/djinni/objc
   )
 
-  if (NOT DJINNI_STATIC_LIB)
-    target_link_libraries(djinni_support_lib
-      "-framework Foundation"
-    )
-  endif()
+  target_link_libraries(djinni_support_lib PUBLIC "-framework Foundation")
 
 endif()
 
@@ -120,10 +115,10 @@ if(DJINNI_WITH_JNI)
 
   install(
     FILES
-    "djinni/jni/djinni_support.hpp"
-    "djinni/jni/Marshal.hpp"
+      "djinni/jni/djinni_support.hpp"
+      "djinni/jni/Marshal.hpp"
     DESTINATION
-    ${CMAKE_INSTALL_INCLUDEDIR}/djinni/jni
+      ${CMAKE_INSTALL_INCLUDEDIR}/djinni/jni
     )
 
   # Do not use the host's jni.h on Android as it is provided automatically by the NDK
@@ -142,9 +137,9 @@ if(DJINNI_WITH_PYTHON)
 
   install(
     FILES
-    "djinni/cwrapper/wrapper_marshal.h"
+      "djinni/cwrapper/wrapper_marshal.h"
     DESTINATION
-    ${CMAKE_INSTALL_INCLUDEDIR}/djinni/cwrapper
+      ${CMAKE_INSTALL_INCLUDEDIR}/djinni/cwrapper
     )
 endif()
 
@@ -155,10 +150,6 @@ if(DJINNI_WITH_CPPCLI)
     message(FATAL_ERROR "Enabling DJINNI_WITH_CPPCLI without MSVC is not supported")
   endif()
 
-  if(NOT DJINNI_STATIC_LIB)
-    message(FATAL_ERROR "DJINNI_WITH_CPPCLI requires DJINNI_STATIC_LIB to be true")
-  endif()
-
   target_include_directories(djinni_support_lib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/support-lib/cppcli/>")
   target_sources(djinni_support_lib PRIVATE ${SRC_CPPCLI})
   source_group("cppcli" FILES ${SRC_CPPCLI})
@@ -183,8 +174,9 @@ if(NOT (DJINNI_WITH_OBJC OR DJINNI_WITH_JNI OR DJINNI_WITH_PYTHON OR DJINNI_WITH
   message(FATAL_ERROR "At least one of DJINNI_WITH_OBJC or DJINNI_WITH_JNI or DJINNI_WITH_PYTHON or DJINNI_WITH_CPPCLI must be enabled.")
 endif()
 
+option(DJINNI_BUILD_TESTING "Build tests" ON)
 
 include(CTest)
-if (BUILD_TESTING)
+if (BUILD_TESTING AND DJINNI_BUILD_TESTING)
   add_subdirectory(test-suite)
 endif()
diff --git a/docs/developer-guide.md b/docs/developer-guide.md
@@ -39,7 +39,7 @@ cd build/test-suite
 ctest
 ```
 
-#### C#
+#### C++/CLI
 
 1. Generate Visual Studio Solution with `-G "Visual Studio 16 2019"`:
     ```sh
@@ -49,6 +49,19 @@ ctest
 3. Build `DjinniCppCliTest`.
 4. Run the tests: <kbd>Test</kbd> > <kbd>Run All Tests</kbd>.
 
+## Preview Documentation
+
+The documentation in `docs` will be rendered as a part of [djinni.xlcpp.dev](https://djinni.xlcpp.dev/).
+
+You can preview how the docs will look like:
+
+```sh
+# install required dependencies
+pip install -r mkdocs-requirements.txt
+# render a live preview of the docs under http://127.0.0.1:8000
+mkdocs serve 
+```
+
 ## Release process
 
 To release a new version of the support-lib, the following steps must be followed:

diff --git a/docs/install.md b/docs/install.md
@@ -1,12 +1,66 @@
 # Installing the Support-Lib
 
-## Conan
+## CMake
+
+### Embedded
+
+To embed the library directly into an existing CMake project, place the entire source tree in a subdirectory and call
+`add_subdirectory()` in your `CMakeLists.txt` file:
+
+```cmake
+project(foo)
+# disable tests
+set(DJINNI_BUILD_TESTING OFF CACHE INTERNAL "")
+# choose for which target language the djinni-support-lib should be compiled.
+# At least one of the following options must be set to true:
+# DJINNI_WITH_JNI, DJINNI_WITH_OBJC, DJINNI_WITH_PYTHON, DJINNI_WITH_CPPCLI
+# In this example the target language depends on the target system:
+if(ANDROID)
+    set(DJINNI_WITH_JNI ON CACHE INTERNAL "")
+elseif(CMAKE_SYSTEM_NAME IN_LIST "Darwin;iOS")
+    set(DJINNI_WITH_OBJC ON CACHE INTERNAL "")
+elseif(CMAKE_SYSTEM_NAME STREQUAL "Windows")
+    set(DJINNI_WITH_CPPCLI ON CACHE INTERNAL "")
+endif()
+add_subdirectory(thirdparty/djinni-support-lib)
+add_library(foo ...)
+target_link_libraries(foo PRIVATE djinni-support-lib::djinni-support-lib)
+```
+
+### Embedded (FetchContent)
+
+[FetchContent](https://cmake.org/cmake/help/v3.14/module/FetchContent.html) can be used to automatically download the repository as a dependency at configuration time.
+
+```cmake
+cmake_minimum_required(VERSION 3.14)
+include(FetchContent)
+project(foo)
+FetchContent_Declare(djinni-support-lib
+  GIT_REPOSITORY https://github.com/cross-language-cpp/djinni-support-lib.git
+  GIT_TAG v1.0.0)
+# set options for djinni-support-lib
+set(DJINNI_BUILD_TESTING OFF CACHE INTERNAL "")
+if(ANDROID)
+    set(DJINNI_WITH_JNI ON CACHE INTERNAL "")
+elseif(CMAKE_SYSTEM_NAME IN_LIST "Darwin;iOS")
+    set(DJINNI_WITH_OBJC ON CACHE INTERNAL "")
+elseif(CMAKE_SYSTEM_NAME STREQUAL "Windows")
+    set(DJINNI_WITH_CPPCLI ON CACHE INTERNAL "")
+endif()
+FetchContent_MakeAvailable(djinni-support-lib)
+add_library(foo ...)
+target_link_libraries(foo PRIVATE djinni-support-lib::djinni-support-lib)
+```
+
+## Package Managers
+
+### Conan
 
 The library is available at [conan-center](https://conan.io/center/djinni-support-lib):
 
 ```text
 [requires]
-djinni-support-lib/0.0.1
+djinni-support-lib/1.0.0
 ```
 
 ### Options
@@ -15,5 +69,5 @@ djinni-support-lib/0.0.1
 | ------ | ------ | ----------- |
 | `shared` | `True`, `False` | Wether to build as shared library. Default: `False` |
 | `fPIC` | `True`, `False` | Default: `True`. Follows the default Conan behaviour. |
-| `target` | `jni`, `objc`, `auto` | The library has different targets for usage with Java or Objective-C. By default (`auto`) the target is determined automatically depending on the target OS (`iOS` → `objc`, `Android` → `jni`). Set this explicitly if you want to build for `macOS`/`Windows`/`Linux`, because on these platforms both targets may be a valid option! |
+| `target` | `jni`, `objc`, `python`, `cppcli`, `auto` | The library has different targets for usage with Java, Objective-C, Python or C++/CLI. By default (`auto`) the target is determined automatically depending on the target OS (`iOS` → `objc`, `Android` → `jni`, `Windows` → `cppcli`). Set this explicitly if you want to build for `macOS`/`Windows`/`Linux`, because on these platforms multiple targets may be a valid option! |
 | `system_java` | `True`, `False` | The library needs to link against the JNI (Java Native Interface) if `target` is `jni`. By default (`True`), `zulu-openjdk/11.0.8` will be installed from conan center for this. Set to `False` to use the systems Java installation instead.  |
diff --git a/mkdocs-requirements.txt b/mkdocs-requirements.txt
@@ -0,0 +1,3 @@
+# dependencies for mkdocs documentation
+mkdocs>=1.1
+mkdocs-material>=7.1.3
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,5 +1,13 @@
 site_name: djinni-support-lib
+markdown_extensions:
+  - pymdownx.tabbed
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - pymdownx.details
+  - admonition
+theme:
+  name: material
 nav:
   - install.md
-  - developer-guide.md
   - python-support.md
+  - developer-guide.md
diff --git a/test-suite/CMakeLists.txt b/test-suite/CMakeLists.txt
@@ -203,8 +203,7 @@ if(DJINNI_WITH_OBJC)
     ${CMAKE_CURRENT_BINARY_DIR}/generated-src/cpp
     ${CMAKE_CURRENT_BINARY_DIR}/generated-src/objc
   )
-  target_link_libraries(DjinniObjcTest djinni_support_lib)
-
+  target_link_libraries(DjinniObjcTest PUBLIC djinni-support-lib::djinni-support-lib)
   xctest_add_bundle(DjinniObjcTestTests DjinniObjcTest ${OBJC_TEST_SRCS})
   target_include_directories(DjinniObjcTestTests PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/handwritten-src/objc/impl)
 
@@ -234,7 +233,7 @@ if(DJINNI_WITH_PYTHON)
     ${CMAKE_CURRENT_SOURCE_DIR}/handwritten-src/pycpp
     ${CMAKE_CURRENT_BINARY_DIR}/generated-src/pycpp
   )
-  target_link_libraries(mylib djinni_support_lib)
+  target_link_libraries(mylib PUBLIC djinni-support-lib::djinni-support-lib)
 
   # Prepare Python 3 environment
   find_package(PythonInterp "3" REQUIRED)
@@ -280,7 +279,7 @@ if(DJINNI_WITH_CPPCLI)
     VS_DOTNET_REFERENCES "System;System.Core"
     COMMON_LANGUAGE_RUNTIME ""
   )
-  target_link_libraries(DjinniCppCli djinni_support_lib)
+  target_link_libraries(DjinniCppCli PUBLIC djinni-support-lib::djinni-support-lib)
 
   add_library(DjinniCppCliTest SHARED
     handwritten-src/cs/ClientInterfaceImpl.cs
@@ -303,5 +302,5 @@ if(DJINNI_WITH_CPPCLI)
     VS_PACKAGE_REFERENCES "nunit_3.13.1;NUnit3TestAdapter_3.17.0;Microsoft.NET.Test.Sdk_16.9.4"
   )
 
-  target_link_libraries(DjinniCppCliTest DjinniCppCli)
+  target_link_libraries(DjinniCppCliTest PUBLIC DjinniCppCli)
 endif()