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.

.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

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]*
 

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
 

examples/lib/simple/.gitignore

@@ -0,0 +1,2 @@
+!/Makefile.example.in
+Makefile.example

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)

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

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
+```

examples/lib/simple/main.c

@@ -0,0 +1,7 @@
+#include "suricata.h"
+
+int main(int argc, char **argv)
+{
+    SuricataMain(argc, argv);
+    return 0;
+}