examples: program linking against library

Provide an example of an extremely simple application that links
against Suricata. This provides a Makefile integrated with the
Suricata build system for in-tree building, as well as an example
Makefile for building out of tree.

Currently this application just wraps SuricataMain and does nothing
else.

diff --git a/.github/workflows/builds.yml b/.github/workflows/builds.yml
index e91392a8dabe372692ed047ebb64116fd48b4ebf..ef8f23e31fce82184c6c886dbfe552da13abb266 100644 (file)
--- a/.github/workflows/builds.yml
+++ b/.github/workflows/builds.yml
@@ -291,15 +291,22 @@ jobs:
           test -e /usr/local/lib/suricata/python/suricata/update/configs/modify.conf
           test -e /usr/local/lib/suricata/python/suricata/update/configs/threshold.in
           test -e /usr/local/lib/suricata/python/suricata/update/configs/update.yaml
-      - name: Build C json filetype plugin
+
+      - name: Test library build in tree
+        working-directory: examples/lib/simple
+        run: make clean all
+
+      - name: Test plugin build in tree
         working-directory: examples/plugins/c-json-filetype
-        run: make
-      - name: Check C json filetype plugin
-        run: test -e examples/plugins/c-json-filetype/filetype.so
-      - name: Installing headers and library
-        run: |
-          make install-headers
-          make install-library
+        run: make clean all
+
+      - name: Install Suricata and library
+        run: make install install-headers install-library
+
+      - name: Test library build out of tree
+        working-directory: examples/lib/simple
+        run: PATH=/usr/local/bin:$PATH make -f Makefile.example clean all
+
       - name: Cleaning source directory for standalone plugin test.
         run: make clean
       - name: Test plugin against installed headers
@@ -312,7 +319,7 @@ jobs:
           sed -i 's/^CPPFLAGS.*HAVE_CONFIG_H//' Makefile
 
           # And build.
-          PATH=/usr/local/bin:$PATH make
+          PATH=/usr/local/bin:$PATH make clean all
 
   almalinux-9-templates:
     name: AlmaLinux 9 Test Templates

diff --git a/Makefile.am b/Makefile.am
index 00503e21f9a411939b83f30f3e451d48b9c7d4fc..8216526fda07db934d702afe5f71274fa31657c6 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -8,9 +8,9 @@ EXTRA_DIST = ChangeLog COPYING LICENSE suricata.yaml.in \
             lua \
             acsite.m4 \
             scripts/generate-images.sh \
-            examples
+            examples/plugins
 SUBDIRS = $(HTP_DIR) rust src qa rules doc contrib etc python ebpf \
-          $(SURICATA_UPDATE_DIR)
+          $(SURICATA_UPDATE_DIR) examples/lib/simple
 
 CLEANFILES = stamp-h[0-9]*
 

diff --git a/configure.ac b/configure.ac
index 95613b674182ac0e0346ad8c62d3c87c89a38cff..c342cb34d55105c8fe65b7c00ab8b813eedf4999 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -2640,6 +2640,7 @@ AC_CONFIG_FILES(python/Makefile python/suricata/config/defaults.py)
 AC_CONFIG_FILES(ebpf/Makefile)
 AC_CONFIG_FILES(libsuricata-config)
 AC_CONFIG_FILES(examples/plugins/c-json-filetype/Makefile)
+AC_CONFIG_FILES(examples/lib/simple/Makefile examples/lib/simple/Makefile.example)
 
 AC_OUTPUT
 

diff --git a/examples/lib/simple/.gitignore b/examples/lib/simple/.gitignore
new file mode 100644 (file)
index 0000000..579841d
--- /dev/null
+++ b/examples/lib/simple/.gitignore
@@ -0,0 +1,2 @@
+!/Makefile.example.in
+Makefile.example

diff --git a/examples/lib/simple/Makefile.am b/examples/lib/simple/Makefile.am
new file mode 100644 (file)
index 0000000..9ebc9a3
--- /dev/null
+++ b/examples/lib/simple/Makefile.am
@@ -0,0 +1,9 @@
+bin_PROGRAMS = simple
+
+simple_SOURCES = main.c
+
+AM_CPPFLAGS = -I$(top_srcdir)/src
+
+simple_LDFLAGS = $(all_libraries) $(SECLDFLAGS)
+simple_LDADD = $(top_builddir)/src/libsuricata_c.a ../../$(RUST_SURICATA_LIB) ../../$(HTP_LDADD) $(RUST_LDADD)
+simple_DEPENDENCIES = $(top_builddir)/src/libsuricata_c.a ../../$(RUST_SURICATA_LIB)

diff --git a/examples/lib/simple/Makefile.example.in b/examples/lib/simple/Makefile.example.in
new file mode 100644 (file)
index 0000000..724becc
--- /dev/null
+++ b/examples/lib/simple/Makefile.example.in
@@ -0,0 +1,12 @@
+LIBSURICATA_CONFIG ?=  @CONFIGURE_PREFIX@/bin/libsuricata-config
+
+SURICATA_LIBS =                `$(LIBSURICATA_CONFIG) --libs`
+SURICATA_CFLAGS :=     `$(LIBSURICATA_CONFIG) --cflags`
+
+all: simple
+
+simple: main.c
+       $(CC) -o $@ $^ $(CFLAGS) $(SURICATA_CFLAGS) $(SURICATA_LIBS)
+
+clean:
+       rm -f simple

diff --git a/examples/lib/simple/README.md b/examples/lib/simple/README.md
new file mode 100644 (file)
index 0000000..930894a
--- /dev/null
+++ b/examples/lib/simple/README.md
@@ -0,0 +1,36 @@
+# Simple Library Example
+
+## Building In Tree
+
+The Suricata build system has created a Makefile that should allow you
+to build this application in-tree on most supported platforms. To
+build simply run:
+
+```
+make
+```
+
+## Building Out of Tree
+
+A Makefile.example has also been generated to use as an example on how
+to build against the library in a standalone application.
+
+First build and install the Suricata library including:
+
+```
+make install-library
+make install-headers
+```
+
+Then run:
+
+```
+make -f Makefile.example
+```
+
+If you installed to a non-standard location, you need to ensure that
+`libsuricata-config` is in your path, for example:
+
+```
+PATH=/opt/suricata/bin:$PATH make -f Makefile.example
+```

diff --git a/examples/lib/simple/main.c b/examples/lib/simple/main.c
new file mode 100644 (file)
index 0000000..0ebb125
--- /dev/null
+++ b/examples/lib/simple/main.c
@@ -0,0 +1,7 @@
+#include "suricata.h"
+
+int main(int argc, char **argv)
+{
+    SuricataMain(argc, argv);
+    return 0;
+}