1 files changed, 165 insertions, 0 deletions
diff --git a/doc/being-consumed-by-cmake.org b/doc/being-consumed-by-cmake.org
new file mode 100644
index 0000000..86c1825
--- /dev/null
+++ b/doc/being-consumed-by-cmake.org
@@ -0,0 +1,165 @@
+* Being consumed by CMake
+
+To support libraries built with JustBuild to be consumed by CMake, the rule
+~["CC", "install-with-deps"]~ can be used. This rule will install the library's
+artifacts, its public headers, and a pkg-config file, which can be used by CMake
+to properly consume the library.
+
+In this example, we show how to build and install the ~ssl~ library with
+JustBuild, so it can be picked up and used by CMake afterwards.
+
+** Example: Build and install the ~ssl~ Library with JustBuild
+
+First make sure that ~just~, ~just-mr~, and ~just-import-git~ are available in
+your ~PATH~. Then, define a new workspace by creating the ~ROOT~ marker.
+
+#+BEGIN_SRC sh
+$ touch ROOT
+#+END_SRC
+
+The ~ssl~ library that we want to use is a defined dependency of the JustBuild
+repository ~just/ssl~. To define a repository for that library, create the
+following ~repos.template.json~ file.
+
+#+SRCNAME: repos.template.json
+#+BEGIN_SRC js
+{ "main": "ssl"
+, "repositories":
+  { "ssl":
+    { "repository": {"type": "file", "path": "."}
+    , "bindings": {"rules": "rules-cc", "just-ssl": "just/ssl"}
+    }
+  }
+}
+#+END_SRC
+
+and import the ~rules-cc~ and JustBuild repository, including its dependency
+~just/ssl~, via:
+
+#+BEGIN_SRC sh
+$ cat repos.template.json \
+  | just-import-git -C - --as just -b master https://github.com/just-buildsystem/justbuild \
+  | just-import-git -C - --as rules-cc -b master https://github.com/just-buildsystem/rules-cc \
+  > repos.json
+$
+#+END_SRC
+
+Next, the following ~TARGETS~ file needs to be provided.
+
+#+SRCNAME: TARGETS
+#+BEGIN_SRC js
+{ "ssl-lib":
+  { "type": ["@", "rules", "CC", "library"]
+  , "name": ["ssl"]
+  , "deps": [["@", "just-ssl", "", "ssl"]]
+  }
+, "ssl-pkg":
+  {"type": ["@", "rules", "CC", "install-with-deps"], "targets": ["ssl-lib"]}
+}
+#+END_SRC
+
+The library target ~ssl-lib~ specifies the name ~"ssl"~ (also used as package
+name) and a dependency on the ~ssl~ library from ~just-ssl~. Note that although
+this library target is merely a "wrapper" (header-only library without headers),
+it could equally well be a full-blown library target. Furthermore, the package
+target ~ssl-pkg~ installs the ~ssl-lib~ target including its dependencies and
+generates a pkg-config file that can be later used by CMake.
+
+Finally, the ~ssl-pkg~ target can be built and installed to a specific ~PREFIX~
+(note that ~OS~ and ~ARCH~ must be set as well).
+
+#+BEGIN_SRC sh
+$ export PREFIX=/tmp/just_ssl
+$ just-mr install -D'{"OS":"linux", "ARCH":"x64_64", "PREFIX":"'$PREFIX'"}' -o $PREFIX ssl-pkg
+INFO: Requested target is [["@","ssl","","ssl-pkg"],{"ARCH":"x64_64","OS":"linux","PREFIX":"/tmp/just_ssl"}]
+INFO: Analysed target [["@","ssl","","ssl-pkg"],{"ARCH":"x64_64","OS":"linux","PREFIX":"/tmp/just_ssl"}]
+INFO: Export targets found: 0 cached, 2 uncached, 0 not eligible for caching
+INFO: Discovered 269 actions, 3 trees, 1 blobs
+INFO: Building [["@","ssl","","ssl-pkg"],{"ARCH":"x64_64","OS":"linux","PREFIX":"/tmp/just_ssl"}].
+PROG: [ 79%] 0 cached, 215 run, 8 processing (["@","just/ssl","","crypto-lib"]#105, ...).
+INFO: Processed 269 actions, 0 cache hits.
+INFO: Artifacts can be found in:
+        /tmp/just_ssl/include/openssl/aead.h [6d78db27d24746b39eacc20374697476e080c9f6:21054:f]
+        ...
+        /tmp/just_ssl/lib/libcrypto.a [df64da43f0168a717d09d609bf0c631d29c86b61:2336092:f]
+        /tmp/just_ssl/lib/libssl.a [77d2c2bfbe3ef3608895c854f1d1f6e1c200efd0:852620:f]
+        /tmp/just_ssl/share/pkgconfig/ssl.pc [9b69c758430f5b5fb6ff7a9b1f1ffc89471509af:406:f]
+$
+#+END_SRC
+
+** Example: Consume the installed ~ssl~ Library with CMake
+
+As an example, a minimal ~main.c~ file is created that depends on the ~ssl~
+library.
+
+#+SRCNAME: main.c
+#+BEGIN_SRC C
+#include <openssl/evp.h>
+
+int main(int argc, char** argv) {
+  OpenSSL_add_all_algorithms();
+  return 0;
+}
+#+END_SRC
+
+In the ~CMakeLists.txt~ file, the ~pkg_check_modules()~ macro can be used to
+determine the compile and linker flags needed to consume our ~ssl~ library with
+CMake.
+
+#+SRCNAME: CMakeLists.txt
+#+BEGIN_SRC cmake
+cmake_minimum_required(VERSION 3.1)
+
+project(test_ssl)
+
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(SSL REQUIRED ssl)
+
+add_executable(main main.c)
+target_include_directories(main PRIVATE ${SSL_INCLUDE_DIRS})
+target_compile_options(main PRIVATE ${SSL_CFLAGS_OTHER})
+target_link_directories(main PRIVATE ${SSL_LIBRARY_DIRS})
+target_link_libraries(main PRIVATE ${SSL_LDFLAGS_OTHER} ${SSL_LIBRARIES})
+#+END_SRC
+
+Note that ~${SSL_LDFLAGS_OTHER}~ can be omitted if the ~ssl-pkg~ target was
+defined with a non-empty value for the field ~"flat-libs"~ (see rule
+documentation of ~["CC", "install-with-deps"]~).
+
+Finally, when running CMake, make sure to set the ~CMAKE_PREFIX_PATH~ to the
+previously used install prefix in order to successfully find the installed ~ssl~
+library and its pkg-config file.
+
+#+BEGIN_SRC sh
+$ cmake -DCMAKE_PREFIX_PATH=/tmp/just_ssl -S . -B /tmp/test_ssl
+-- The C compiler identification is GNU 10.2.1
+-- The CXX compiler identification is GNU 10.2.1
+-- Detecting C compiler ABI info
+-- Detecting C compiler ABI info - done
+-- Check for working C compiler: /usr/bin/cc - skipped
+-- Detecting C compile features
+-- Detecting C compile features - done
+-- Detecting CXX compiler ABI info
+-- Detecting CXX compiler ABI info - done
+-- Check for working CXX compiler: /usr/bin/c++ - skipped
+-- Detecting CXX compile features
+-- Detecting CXX compile features - done
+-- Found PkgConfig: /usr/bin/pkg-config (found version "0.29.2") 
+-- Checking for module 'ssl'
+--   Found ssl, version unknown
+-- Configuring done
+-- Generating done
+-- Build files have been written to: /tmp/test_ssl
+$ cmake --build /tmp/test_ssl
+[ 50%] Building CXX object CMakeFiles/main.dir/main.c.o
+[100%] Linking CXX executable main
+[100%] Built target main
+$
+#+END_SRC
+
+Note that if the package is moved to a different location, the ~prefix~ variable
+within the pkg-config file ~share/pkgconfig/ssl.pc~ must be updated as well.
+Alternatively, CMake can be instructed to automatically guess the correct prefix
+by setting the variable ~PKG_CONFIG_ARGN~ to ~"--define-prefix"~ (either on the
+command line or in the ~CMakeLists.txt~). However, this is a fairly recent CMake
+feature and requires at least CMake version 3.22.