Author: brane Date: Tue Jul 1 02:21:08 2025 New Revision: 1926882 URL: http://svn.apache.org/viewvc?rev=1926882&view=rev Log: * README: Updated docs for SCons and CMake.
Modified: serf/trunk/README Modified: serf/trunk/README URL: http://svn.apache.org/viewvc/serf/trunk/README?rev=1926882&r1=1926881&r2=1926882&view=diff ============================================================================== --- serf/trunk/README (original) +++ serf/trunk/README Tue Jul 1 02:21:08 2025 @@ -37,7 +37,10 @@ Fetch the scons-local package: To build serf: -$ scons APR=/path/to/apr APU=/path/to/apu OPENSSL=/openssl/base PREFIX=/path/to/prefix +$ scons PREFIX=/path/to/prefix \ + APR=/path/to/apr APU=/path/to/apr-util \ + OPENSSL=/path/to/openssl ZLIB=/path/to/zlib \ + BROTLI=/path/to/brotli GSSAPI=/path/to/kerberos The switches are recorded into .saved_config, so they only need to be specified the first time scons is run. @@ -45,14 +48,31 @@ specified the first time scons is run. PREFIX should specify where serf should be installed. PREFIX defaults to /usr/local. -The default for the other three switches (APR, APU, OPENSSL) is /usr. +The default for the mandatory dependencies (APR, APU, OPENSSL, ZLIB) is /usr. The build system looks for apr-1-config at $APR/bin/apr-1-config, or the path should indicate apr-1-config itself. Similarly for the path -to apu-1-config. +to apu-1-config in $APU or $APU/bin/apu-1-config. + +OPENSSL should specify the root of the install (e.g., /opt/local). The +includes will be found $OPENSSL/include/openssl and libraries at $OPENSSL/lib. + +OPENSSL should specify the root of the install. The includes will be found +$ZLIB/include and libraries at $ZLIB/lib. + +The BROTLI and GSSAPI dependencies are optional. + +BROTLI should be the path to the installation of the Brotli compression +library; for example, BROTLI=/usr/local. The includes will be found +in $BROTLI/include/brotli and the libraries in $BROTLI/lib. + +GSSAPI should be the path to the installation of a package that provides +the GSSAPI implementation such as Kerberos5 or Heimdal. SCons will look +for the configuration program $GSSAPI/bin/krb5-config. + +NOTE: Do not use the GSSAPI switch on Windows; it provides the SSPI API + which Serf uses by default on that platform. -OPENSSL should specify the root of the install (eg. /opt/local). The -includes will be found OPENSSL/include and libraries at OPENSSL/lib. If you wish to use VPATH-style builds (where objects are created in a distinct directory from the source), you can use: @@ -103,13 +123,17 @@ $ scons -c Get the sources, either a release tarball or by checking out the official repository. The CMake build system currently only exists in -/trunk and it will be included in the 1.4 release. +trunk and it will be included in the 1.4 release. The process for building on Unix and Windows is the same. $ cmake -B out [build options] $ cmake --build out +or, with a multi-config generator: + + $ cmake --build out --config Release + "out" in the commands above is the build directory used by CMake. Build options can be added, for example: @@ -120,7 +144,30 @@ Build options can be listed using: $ cmake -LH -Windows tricks: +By default, CMake will look for dependencies in ${CMAKE_SEARCH_PREFIX}, which +you can override on the command line, e.g.:: + + $ cmake -DCMAKE_SEARCH_PREFIX=/opt + +The search for each the five dependencies can be modified by setting their +*_ROOT CMake variables: + + $ cmake -DAPR_ROOR=/path/to/apr \ + -DAPRUtil_ROOT=/path/to/apr-util \ + -DOPENSSL_ROOT_DIR=/path/to/openssl \ + -DZLIB_ROOT=/path/to/zlib \ + -DBrotli_ROOT=/path/to/brotli \ + -DGSSAPI_ROOT=/path/to/kerberos5 + + +1.2.2 MacOS specifics + +The CMake build system can search for dependencies from Homebrew or +MacPorts: use 'cmake -DUSE_HOMEBREW=ON' to search for Homebrew packages, +or 'cmake -DUSE_MACPORTS=ON' to search installed MacPorts. Just not both. + + +1.2.3 Windows tricks - Modern versions of Microsoft Visual Studio provide support for CMake projects out-of-box, including intellisense, integrated @@ -154,15 +201,33 @@ Windows tricks: <VCPKG_ROOT>/scripts/buildsystems/vcpkg.cmake -1.2.1 Running the test suite -$ cd out -$ ctest -# this only seems to run part of the testsuite? -$ ./test/test_all -# fails due to missing certificates -$ cp ../test/*.pem ../test/certs test/ -$ ./test/test_all -# Succeeds? +1.2.4 Running the test suite + +To run the test suite, go to the CMake output directory, then: + + $ ctest + +or, with a multi-config generator: + + $ ctest -C Release + +This is equivalent to + + $ cmake --build out --target test + +or + + $ cmake --build out --config Release --target test + +(or, on Windows using the Visual Studio generator, which always has to be + special and different for no discernible benefit: + + $ cmake --build out --config Release --target run_tests +) + + +1.2.5 Installing Apache Serf -This should be described in detail. + $ cmake --build out --target install + $ cmake --build out --config Release --target install