This is an automated email from the ASF dual-hosted git repository.
cmcfarlen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new dc8fb70d09 Add utility files for building external plugins (#11008)
dc8fb70d09 is described below
commit dc8fb70d09d5b33ac5beaa1ee2922e7721fbd754
Author: Chris McFarlen <[email protected]>
AuthorDate: Tue Feb 13 08:20:50 2024 -0600
Add utility files for building external plugins (#11008)
* Add Findtsapi.cmake and ts.pc files
* add docs for building a plugin
* skip linking libraries by default
* mention using both verifies for some plugins
---------
Co-authored-by: Chris McFarlen <[email protected]>
---
CMakeLists.txt | 7 ++
Findtsapi.cmake.in | 76 ++++++++++++++++++++++
.../plugins/building-plugins.en.rst | 56 ++++++++++++++++
ts.pc.in | 11 ++++
4 files changed, 150 insertions(+)
diff --git a/CMakeLists.txt b/CMakeLists.txt
index ac0072d493..947625d237 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -745,6 +745,13 @@ install(
)
install(SCRIPT cmake/post_install.cmake)
+# Generate pkg-config and cmake config files
+configure_file(ts.pc.in ts.pc @ONLY)
+configure_file(Findtsapi.cmake.in Findtsapi.cmake @ONLY)
+
+install(FILES "${PROJECT_BINARY_DIR}/ts.pc" DESTINATION
${CMAKE_INSTALL_LIBDIR}/pkgconfig)
+install(FILES "${PROJECT_BINARY_DIR}/Findtsapi.cmake" DESTINATION
${CMAKE_INSTALL_LIBDIR}/cmake)
+
# Display build summary
include(CMakePrintHelpers)
message(STATUS "Build Summary:")
diff --git a/Findtsapi.cmake.in b/Findtsapi.cmake.in
new file mode 100644
index 0000000000..0de13d7358
--- /dev/null
+++ b/Findtsapi.cmake.in
@@ -0,0 +1,76 @@
+#######################
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
contributor license
+# agreements. See the NOTICE file distributed with this work for additional
information regarding
+# copyright ownership. The ASF licenses this file to you under the Apache
License, Version 2.0
+# (the "License"); you may not use this file except in compliance with the
License. You may obtain
+# a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
distributed under the License
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express
+# or implied. See the License for the specific language governing permissions
and limitations under
+# the License.
+#
+#######################
+
+# Findtsapi.cmake
+#
+# This will define the following variables
+#
+# tsapi_FOUND
+# tsapi_LIBRARY
+# tsapi_INCLUDE_DIRS
+#
+# and the following imported targets
+#
+# ts::tsapi
+#
+
+
+set(tsapi_ROOT @CMAKE_INSTALL_PREFIX@ CACHE PATH "The base path for
trafficserver")
+find_library(tsapi_LIBRARY NAMES tsapi PATH_SUFFIXES lib lib/trafficserver
REQUIRED)
+find_path(tsapi_INCLUDE_DIR NAMES ts/ts.h)
+
+mark_as_advanced(tsapi_FOUND tsapi_LIBRARY tsapi_LIBRARY tsapi_INCLUDE_DIR)
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(tsapi REQUIRED_VARS tsapi_LIBRARY
tsapi_INCLUDE_DIR)
+
+if(tsapi_FOUND)
+ set(tsapi_INCLUDE_DIRS ${tsapi_INCLUDE_DIR})
+endif()
+
+if(tsapi_FOUND AND NOT TARGET ts::tsapi)
+ add_library(ts::tsapi INTERFACE IMPORTED)
+ target_include_directories(ts::tsapi INTERFACE ${tsapi_INCLUDE_DIRS})
+ target_link_libraries(ts::tsapi INTERFACE ${tsapi_LIBRARY})
+endif()
+
+set(TRAFFICSERVER_PLUGIN_DIR @CMAKE_INSTALL_FULL_LIBEXECDIR@)
+set(CMAKE_SHARED_LIBRARY_PREFIX "")
+
+function(add_atsplugin name)
+ add_library(${name} MODULE ${ARGN})
+ set_target_properties(${name} PROPERTIES PREFIX "")
+ set_target_properties(${name} PROPERTIES SUFFIX ".so")
+ install(TARGETS ${name} DESTINATION ${TRAFFICSERVER_PLUGIN_DIR})
+endfunction()
+
+if(APPLE)
+ set(CMAKE_MODULE_LINKER_FLAGS "-undefined dynamic_lookup")
+endif()
+
+function(verify_global_plugin target)
+ add_test(NAME verify_${target}
+ COMMAND ${tsapi_ROOT}/bin/traffic_server -C "verify_global_plugin
$<TARGET_FILE:${target}>"
+ )
+endfunction()
+
+function(verify_remap_plugin target)
+ add_test(NAME verify_${target}
+ COMMAND ${tsapi_ROOT}/bin/traffic_server -C "verify_remap_plugin
$<TARGET_FILE:${target}>"
+ )
+endfunction()
+
diff --git a/doc/developer-guide/plugins/building-plugins.en.rst
b/doc/developer-guide/plugins/building-plugins.en.rst
index 5494e404d2..16c592993a 100644
--- a/doc/developer-guide/plugins/building-plugins.en.rst
+++ b/doc/developer-guide/plugins/building-plugins.en.rst
@@ -22,3 +22,59 @@
Building Plugins
****************
+The traffic server build provides two ways to help you build your own plugins.
+First, it provides a pkg-config file name ts.pc installed in `lib/pkgconfig`.
+You can use this to discover include and library directories needed to build
+your plugin. The other provided option is a cmake find-package script that
both
+locates the traffic server libraries, but also provides some function for
+building a plugin as well as verifying that the plugin produced is loadable by
+traffic server.
+
+Example Plugin Project
+======================
+
+.. code-block:: text
+
+ cmake_minimum_required(VERSION 3.20..3.27)
+ project(ats-plugin-test)
+
+ find_package(tsapi REQUIRED)
+
+ enable_testing()
+
+ add_atsplugin(myplugin myplugin.cc)
+ verify_remap_plugin(myplugin)
+
+This example :file:`CMakeLists.txt` finds the tsapi package which provides the
+:func:`add_atsplugin` and :func:`verify_remap_plugin` functions.
+:func:`add_atsplugin` does all of the necessary cmake commands to build a
+plugins module .so. The function takes the plugin target name and a list of
+source files that make up the project. If the plugin requires additional
+libraries, those can be linked with the :func:`target_link_libraries` cmake
+function.
+
+After the plugin target is created, a verify test target can be created. This
+will add a cmake test declaration and at test time, will run traffic_server in
+its verify plugin mode. There are two verify functions provided,
+:func:`verify_remap_plugin` and :func:`verify_global_plugin`. Use the relevant
+function for your plugin type (or call both if your plugin is both types). The
+test will fail if either your plugin does not define the required init function
+(:func:`TSRemapInit` or :func:`TSPluginInit`), or if your plugin calls any
+undefined symbols.
+
+If traffic server is installed in a standard location, or from a package, you
+might not need the -D options below, but run these commands to build and test
+your plugin:
+
+.. code-block:: text
+
+ cmake -B build -S . -DCMAKE_MODULE_PATH=/opt/ats/lib/cmake
+ -DCMAKE_INSTALL_PREFIX=/opt/ats
+ cmake --build build
+ cmake --build build -t test
+ cmake --install build
+
+If all of these succeed, you should be able to configure and test your new
+plugin!
+
+
diff --git a/ts.pc.in b/ts.pc.in
new file mode 100644
index 0000000000..038a9f51e3
--- /dev/null
+++ b/ts.pc.in
@@ -0,0 +1,11 @@
+prefix=@CMAKE_INSTALL_PREFIX@
+exec_prefix=@CMAKE_INSTALL_FULL_LIBEXECDIR@
+includedir=@CMAKE_INSTALL_FULL_INCLUDEDIR@
+libdir=@CMAKE_INSTALL_FULL_LIBDIR@
+
+Name: trafficserver
+Description: Apache Traffic Server
+Version: @TS_VERSION_STRING@
+Requires:
+Libs:
+Cflags: -I${includedir}/ts
