Add out-of-tree CMake plugin example for issue #237

Provides a working example demonstrating the correct way to build
SEMS plugins with CMake when building outside the SEMS source tree.

Files:
- MyApp.cpp: Simple example plugin implementation
- CMakeLists.txt: Correct configuration using SemsPlugin.cmake helper
- README.md: Build instructions and explanation

This example uses the SemsPlugin.cmake helper to ensure:
- MODULE library type (not SHARED)
- No static linking of SEMS core
- Correct symbol visibility for dlsym()
- Platform-specific linker flags

Includes verification target to check that session_factory_create
symbol is properly exported.

Author: Marcel Hecko

apps/examples/out_of_tree_cmake/CMakeLists.txt

@@ -0,0 +1,105 @@
+# Example: Out-of-Tree SEMS Plugin with CMake
+#
+# This demonstrates the CORRECT way to build a SEMS plugin using CMake
+# when building outside the SEMS source tree.
+#
+# Build instructions:
+#   mkdir build && cd build
+#   cmake -DSEMS_SOURCE_DIR=/path/to/sems ..
+#   make
+#   nm -D myapp_cmake.so | grep session_factory_create  # verify symbol
+
+cmake_minimum_required(VERSION 3.15)
+project(myapp_cmake_example)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# ============================================================================
+# SEMS Configuration
+# ============================================================================
+
+# Path to SEMS source directory (required)
+set(SEMS_SOURCE_DIR "" CACHE PATH "Path to SEMS source directory")
+
+if(NOT SEMS_SOURCE_DIR)
+    message(FATAL_ERROR 
+        "SEMS_SOURCE_DIR not set. Please specify:\n"
+        "  cmake -DSEMS_SOURCE_DIR=/path/to/sems .."
+    )
+endif()
+
+if(NOT EXISTS "${SEMS_SOURCE_DIR}/cmake/SemsPlugin.cmake")
+    message(FATAL_ERROR 
+        "SEMS source directory invalid: ${SEMS_SOURCE_DIR}\n"
+        "Cannot find cmake/SemsPlugin.cmake"
+    )
+endif()
+
+# Include the SEMS plugin helper
+include(${SEMS_SOURCE_DIR}/cmake/SemsPlugin.cmake)
+
+# ============================================================================
+# Plugin Configuration
+# ============================================================================
+
+# Add the plugin using the helper function
+# This automatically:
+#  - Creates a MODULE library (for dlopen)
+#  - Sets MODULE_NAME definition
+#  - Configures proper symbol visibility
+#  - Sets platform-specific linker flags
+sems_add_plugin(myapp_cmake
+    MyApp.cpp
+)
+
+# Add SEMS core include directory
+sems_plugin_include_directories(myapp_cmake
+    ${SEMS_SOURCE_DIR}/core
+)
+
+# Link external libraries only
+# DO NOT link SEMS core libraries statically!
+# They will be resolved from the SEMS binary at runtime.
+sems_plugin_link_libraries(myapp_cmake
+    pthread
+    # Add your external dependencies here (PocoNet, etc.)
+)
+
+# Install to standard location
+sems_install_plugin(myapp_cmake)
+
+# ============================================================================
+# Verification
+# ============================================================================
+
+# Custom target to verify the symbol is exported correctly
+find_program(NM_PROGRAM nm)
+if(NM_PROGRAM)
+    add_custom_target(verify_symbol
+        COMMAND ${CMAKE_COMMAND} -E echo "Verifying session_factory_create symbol..."
+        COMMAND ${NM_PROGRAM} -D ${CMAKE_CURRENT_BINARY_DIR}/myapp_cmake.so | grep session_factory_create || (echo "ERROR: Symbol not found!" && exit 1)
+        COMMAND ${CMAKE_COMMAND} -E echo "✓ Symbol exported correctly!"
+        DEPENDS sems_myapp_cmake
+        COMMENT "Verifying plugin symbol export"
+    )
+    
+    message(STATUS "Run 'make verify_symbol' after building to verify the plugin")
+endif()
+
+# ============================================================================
+# Summary
+# ============================================================================
+
+message(STATUS "========================================")
+message(STATUS "Out-of-Tree Plugin Example")
+message(STATUS "========================================")
+message(STATUS "Plugin name:    myapp_cmake")
+message(STATUS "SEMS source:    ${SEMS_SOURCE_DIR}")
+message(STATUS "Output:         ${CMAKE_CURRENT_BINARY_DIR}/myapp_cmake.so")
+message(STATUS "========================================")
+message(STATUS "After building:")
+message(STATUS "  1. Run: make verify_symbol")
+message(STATUS "  2. Install: sudo cp myapp_cmake.so /usr/lib/sems/plug-in/")
+message(STATUS "  3. Configure: Add 'load_plugins=myapp_cmake' to sems.conf")
+message(STATUS "========================================")

apps/examples/out_of_tree_cmake/MyApp.cpp

@@ -0,0 +1,73 @@
+/*
+ * Example out-of-tree SEMS plugin built with CMake
+ * 
+ * This demonstrates the correct way to build a SEMS plugin
+ * using CMake when building outside the SEMS source tree.
+ * 
+ * See CMakeLists.txt for the build configuration.
+ */
+
+#include "AmApi.h"
+#include "AmSession.h"
+#include "log.h"
+
+#include <string>
+#include <map>
+
+#define MOD_NAME "myapp_cmake"
+
+using std::string;
+using std::map;
+
+class MyAppFactory: public AmSessionFactory
+{
+public:
+    MyAppFactory(const string& _app_name)
+      : AmSessionFactory(_app_name)
+    {
+        DBG("MyAppFactory created\n");
+    }
+    
+    int onLoad() {
+        DBG("MyAppFactory::onLoad()\n");
+        return 0;
+    }
+    
+    AmSession* onInvite(const AmSipRequest& req, const string& app_name,
+                       const map<string,string>& app_params);
+};
+
+class MyAppDialog : public AmSession
+{
+public:
+    MyAppDialog() {
+        DBG("MyAppDialog created\n");
+    }
+    
+    ~MyAppDialog() {
+        DBG("MyAppDialog destroyed\n");
+    }
+    
+    void onSessionStart() {
+        DBG("MyAppDialog::onSessionStart - Hello from CMake-built plugin!\n");
+        // Just log and hang up for this example
+        dlg->bye();
+        setStopped();
+    }
+    
+    void onBye(const AmSipRequest& req) {
+        DBG("MyAppDialog::onBye\n");
+        setStopped();
+    }
+};
+
+AmSession* MyAppFactory::onInvite(const AmSipRequest& req, const string& app_name,
+                                 const map<string,string>& app_params)
+{
+    DBG("MyAppFactory::onInvite\n");
+    return new MyAppDialog();
+}
+
+// This macro creates the extern "C" function that SEMS will call
+// The symbol "session_factory_create" must be visible via dlsym()
+EXPORT_SESSION_FACTORY(MyAppFactory, MOD_NAME);

apps/examples/out_of_tree_cmake/README.md

@@ -0,0 +1,117 @@
+# Out-of-Tree SEMS Plugin with CMake
+
+This example demonstrates the **correct** way to build a SEMS plugin using CMake when building outside the SEMS source tree.
+
+## The Issue (GitHub #237)
+
+When building SEMS plugins with CMake incorrectly, they compile fine but fail at runtime:
+```
+[AmPlugIn.cpp:818] INFO: could not find any application matching configured criteria
+```
+
+This happens when the `session_factory_create` symbol (created by `EXPORT_SESSION_FACTORY`) is not properly exported.
+
+## This Example
+
+This example shows the **correct** approach using the SEMS plugin helper.
+
+### Files
+
+- `MyApp.cpp` - Simple plugin implementation
+- `CMakeLists.txt` - Correct CMake configuration using `SemsPlugin.cmake`
+
+### Key Points
+
+1. **Uses `MODULE` library type** (not `SHARED`)
+2. **Does NOT statically link SEMS core**
+3. **Sets correct symbol visibility**
+4. **Includes platform-specific settings**
+
+## Building
+
+```bash
+# Create build directory
+mkdir build && cd build
+
+# Configure (point to SEMS source)
+cmake -DSEMS_SOURCE_DIR=/path/to/sems/source ..
+
+# Build
+make
+
+# Verify the symbol is exported
+make verify_symbol
+```
+
+Expected output from verification:
+```
+✓ Symbol exported correctly!
+```
+
+## Testing
+
+1. Copy the plugin:
+   ```bash
+   sudo cp myapp_cmake.so /usr/lib/sems/plug-in/
+   ```
+
+2. Configure SEMS (`/etc/sems/sems.conf`):
+   ```
+   load_plugins=myapp_cmake
+   application=myapp_cmake
+   ```
+
+3. Start SEMS and make a test call
+
+4. Check logs for:
+   ```
+   [sems] DEBUG: application 'myapp_cmake' loaded.
+   [myapp_cmake] DEBUG: MyAppFactory created
+   [myapp_cmake] DEBUG: MyAppDialog::onSessionStart - Hello from CMake-built plugin!
+   ```
+
+## How It Works
+
+The `CMakeLists.txt` uses `SemsPlugin.cmake` helper:
+
+```cmake
+include(${SEMS_SOURCE_DIR}/cmake/SemsPlugin.cmake)
+
+sems_add_plugin(myapp_cmake MyApp.cpp)
+sems_plugin_include_directories(myapp_cmake ${SEMS_SOURCE_DIR}/core)
+sems_plugin_link_libraries(myapp_cmake pthread)
+```
+
+This automatically:
+- Creates a `MODULE` library (for `dlopen()`)
+- Sets `MODULE_NAME` definition
+- Configures symbol visibility to `default`
+- Adds platform-specific linker flags
+- Links only external libraries (not SEMS core)
+
+## Common Mistakes (What NOT to Do)
+
+### ❌ Wrong: Using SHARED
+```cmake
+add_library(myapp SHARED MyApp.cpp)  # WRONG!
+```
+
+### ❌ Wrong: Statically linking SEMS core
+```cmake
+target_link_libraries(myapp 
+    "-Wl,--whole-archive"
+    ${SEMS_DIR}/core/libsems_core.a
+    "-Wl,--no-whole-archive")  # WRONG!
+```
+
+### ❌ Wrong: Hidden symbol visibility
+```cmake
+set_target_properties(myapp PROPERTIES
+    CXX_VISIBILITY_PRESET hidden)  # WRONG!
+```
+
+## See Also
+
+- `cmake/SemsPlugin.cmake` - Plugin helper functions
+- `doc/BuildingOutOfTreePlugins.md` - Detailed documentation
+- `cmake/module.rules.txt` - How SEMS builds its own plugins