Add integration tools for every public ST API, with a runner and CI. v1.9.1

.github/workflows/test.yml

@@ -23,6 +23,15 @@ jobs:
       # Tests
       - name: Run ST utest
         run: make ${{ matrix.target }} && ./obj/st_utest
+      - name: Run ST tools
+        run: ./auto/tools.sh
+      - name: Run ST tools in the SRS build
+        run: EXTRA_CFLAGS=-DMALLOC_STACK ./auto/tools.sh
+      - name: Run ST tools with ASAN
+        if: matrix.name == 'linux-x64'
+        run: |
+          EXTRA_CFLAGS="-DMALLOC_STACK -DMD_ASAN -fsanitize=address -fno-omit-frame-pointer" \
+              LDFLAGS=-fsanitize=address ./auto/tools.sh
 
   coverage:
     name: actions-test-coverage

.gitignore

@@ -23,3 +23,4 @@ cmake-build-debug
 /ide/st_clion/Testing/
 .DS_Store
 
+/tasks

CHANGELOG.md

@@ -4,6 +4,7 @@ The changelog for the [srs](https://github.com/ossrs/state-threads/tree/srs) bra
 
 ## ST 1.9 Changelog
 
+* 2026-10-03, Tools: Add integration tools for every public API, run by auto/tools.sh in CI, [#41](https://github.com/ossrs/state-threads/pull/41). v1.9.1
 * 2026-09-30, Changelog: Move the change list from README to CHANGELOG.md, and add the patch version. v1.9.0
 
 ## Before v1.9.0

Makefile

@@ -33,7 +33,7 @@
 # GPL.
 
 # This is the full version of the libst library - modify carefully
-VERSION     = 1.9.0
+VERSION     = 1.9.1
 
 ##########################
 # Supported OSes:
@@ -241,7 +241,7 @@ endif
 ifeq ($(OS),)
 ST_ALL      = unknown
 else
-ST_ALL      = $(TARGETDIR) $(LIBRARIES) $(HEADER) $(DESC)
+ST_ALL      = $(TARGETDIR) $(LIBRARIES) $(HEADER) $(DESC) obj-link
 endif
 
 all: $(ST_ALL)
@@ -258,13 +258,17 @@ unknown:
 st.pc:	st.pc.in
 	sed "s/@VERSION@/${VERSION}/g" < $< > $@
 
+# Point obj to this platform on every build, even when the library is up to date.
+.PHONY: obj-link
+obj-link:
+	rm -f obj; $(LN) $(LNFLAGS) $(TARGETDIR) obj
+
 $(TARGETDIR):
 	if [ ! -d $(TARGETDIR) ]; then mkdir $(TARGETDIR); fi
 
 $(SLIBRARY): $(OBJS)
 	$(AR) $(ARFLAGS) $@ $(OBJS)
 	$(RANLIB) $@
-	rm -f obj; $(LN) $(LNFLAGS) $(TARGETDIR) obj
 
 $(DLIBRARY): $(OBJS:%.o=%-pic.o)
 	$(LD) $(LDFLAGS) $^ -o $@

auto/tools.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+#
+# Build ST, then run every integration tool in tools/ under each event system.
+#
+# The build comes from the environment, empty by default:
+#   EXTRA_CFLAGS  passed to the library build, such as -DMALLOC_STACK
+#   LDFLAGS       passed to the tool link, such as -fsanitize=address
+#
+# Examples:
+#   ./auto/tools.sh
+#   EXTRA_CFLAGS=-DMALLOC_STACK ./auto/tools.sh
+#   EXTRA_CFLAGS="-DMALLOC_STACK -DMD_ASAN -fsanitize=address -fno-omit-frame-pointer" \
+#       LDFLAGS=-fsanitize=address ./auto/tools.sh
+#
+# Each tool reads ST_TOOL_EVENTSYS, select or alt. It prints "<name> <eventsys> OK"
+# per run, or "FAILED <name> <eventsys>" with the output, and exits 1 at the first failure.
+
+cd "$(dirname "$0")/.." || exit 1
+
+ST_TARGET=linux-debug
+if [[ $(uname -s) == Darwin ]]; then
+    ST_TARGET=darwin-debug
+fi
+
+echo "Build ST with make -B $ST_TARGET EXTRA_CFLAGS=\"$EXTRA_CFLAGS\""
+# -B rebuilds every object, so a change of flags never links a stale library.
+if ! out=$(make -B $ST_TARGET EXTRA_CFLAGS="$EXTRA_CFLAGS" 2>&1); then
+    echo "$out"
+    echo "FAILED build ST"
+    exit 1
+fi
+
+for dir in tools/*/; do
+    name=$(basename "$dir")
+    # -W relinks the tool, because the binaries are shared across platforms and builds.
+    if ! out=$(make -C "$dir" -W "$name.c" LDFLAGS="$LDFLAGS" 2>&1); then
+        echo "$out"
+        echo "FAILED build $name"
+        exit 1
+    fi
+
+    for eventsys in select alt; do
+        if ! out=$(cd "$dir" && ST_TOOL_EVENTSYS=$eventsys "./$name" 2>&1); then
+            echo "$out"
+            echo "FAILED $name $eventsys"
+            exit 1
+        fi
+        echo "$name $eventsys OK"
+    done
+done
+
+echo "All tools OK"

public.h

@@ -47,10 +47,10 @@
 #include <errno.h>
 #include <poll.h>
 
-#define ST_VERSION	    "1.9.0"
+#define ST_VERSION	    "1.9.1"
 #define ST_VERSION_MAJOR    1
 #define ST_VERSION_MINOR    9
-#define ST_VERSION_PATCH    0
+#define ST_VERSION_PATCH    1
 
 /* Undefine this to remove the context switch callback feature. */
 #define ST_SWITCH_CB

st.spec

@@ -1,6 +1,6 @@
 Summary:	State Threads Library
 Name:		st
-Version:	1.9.0
+Version:	1.9.1
 Release:	1
 Copyright:	MPL 1.2 or GPL 2+
 Packager:	Wesley W. Terpstra <wesley@terpstra.ca>

tools/backtrace/Makefile

@@ -13,7 +13,7 @@ CFLAGS      += -arch $(CPU_ARCHS)
 endif
 
 ./backtrace: backtrace.c $(LDLIBS)
-	$(CC) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) -Wall -o $@ $^ $(LDLIBS)
+	$(CC) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) -Wall -o $@ $< $(LDLIBS)
 
 clean:
 	cd ../.. && make clean

tools/backtrace/backtrace.c

@@ -8,6 +8,7 @@
 #include <execinfo.h>
 #include <stdio.h>
 #include <stdlib.h>
+#include <string.h>
 
 #include <st.h>
 
@@ -142,6 +143,26 @@ void bar2()
 #endif
 
 int always_use_builtin = 0;
+int failed = 0;
+
+// Whether the frame is the function, such as "bar + 48" on macOS or "./backtrace(bar+0x1c)" on Linux.
+int is_frame_of(const char* frame, const char* name)
+{
+    char on_macos[64], on_linux[64];
+    snprintf(on_macos, sizeof(on_macos), " %s + ", name);
+    snprintf(on_linux, sizeof(on_linux), "(%s+", name);
+    return strstr(frame, on_macos) || strstr(frame, on_linux);
+}
+
+// Whether the frames hold the functions in order, from the callee up to the coroutine start.
+int has_frames(char** symbols, int nn_symbols, const char** names, int nn_names)
+{
+    int i, j = 0;
+    for (i = 0; i < nn_symbols && j < nn_names; i++) {
+        if (is_frame_of(symbols[i], names[j])) j++;
+    }
+    return j == nn_names;
+}
 
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wframe-address"
@@ -186,8 +207,20 @@ void bar() {
     for (int i = 0; i < nn_addresses; i++) {
         printf("%s\n", symbols[i]);
     }
+
+    // The return addresses from __builtin_return_address(0) begin at the caller foo, not bar. Only level 0 is required,
+    // because GCC on aarch64 returns NULL for any level above 0.
+    const char* backtrace_frames[] = {"bar", "foo", "start"};
+    const char* builtin_frames[] = {"foo"};
+    int ok = always_use_builtin ? has_frames(symbols, nn_addresses, builtin_frames, 1)
+        : has_frames(symbols, nn_addresses, backtrace_frames, 3);
     free(symbols);
 
+    if (!ok) {
+        printf("bar FAILED, no frames of the coroutine\n");
+        failed = 1;
+        return;
+    }
     printf("bar OK\n");
     return;
 }
@@ -217,12 +250,18 @@ int main(int argc, char** argv)
         always_use_builtin = 1;
     }
 
-    st_init();
+    if (st_init() != 0) {
+        printf("st_init failed\n");
+        return 1;
+    }
 
-    st_thread_create(start, NULL, 0, 0);
-    st_thread_exit(NULL);
+    st_thread_t trd = st_thread_create(start, NULL, 1, 0);
+    if (!trd || st_thread_join(trd, NULL) != 0) {
+        printf("coroutine failed\n");
+        return 1;
+    }
 
-    printf("main done\n");
-    return 0;
+    printf("main done, failed=%d\n", failed);
+    return failed;
 }
 

tools/helloworld/Makefile

@@ -13,7 +13,7 @@ CFLAGS      += -arch $(CPU_ARCHS)
 endif
 
 ./helloworld: helloworld.c $(LDLIBS)
-	$(CC) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) -Wall -o $@ $^ $(LDLIBS)
+	$(CC) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) -Wall -o $@ $< $(LDLIBS)
 
 clean:
 	cd ../.. && make clean

tools/helloworld/helloworld.c

@@ -2,19 +2,32 @@
 /* Copyright (c) 2013-2026 The SRS Authors */
 
 #include <stdio.h>
+#include <stdlib.h>
 
 #include <st.h>
 
+// Usage: ./helloworld [count], where count defaults to 10, one line every 10ms.
 int main(int argc, char** argv)
 {
-    st_init();
+    int count = 10;
+    if (argc > 1 && (count = atoi(argv[1])) <= 0) {
+        printf("Invalid count %s\n", argv[1]);
+        return 1;
+    }
+
+    if (st_init() != 0) {
+        printf("st_init failed\n");
+        return 1;
+    }
 
     int i;
-    for (i = 0; i < 10000; i++) {
+    for (i = 0; i < count; i++) {
         printf("#%03d, Hello, state-threads world!\n", i);
-        st_sleep(1);
+        if (st_usleep(10 * 1000) != 0) {
+            printf("st_usleep failed\n");
+            return 1;
+        }
     }
 
     return 0;
 }
-

tools/key/.gitignore

@@ -0,0 +1 @@
+key

tools/pcs/Makefile → tools/key/Makefile

@@ -1,6 +1,7 @@
 .PHONY: clean
 
-CFLAGS=-g -O0
+LDLIBS=../../obj/libst.a
+CFLAGS=-g -O0 -I../../obj -I.. -DDEBUG
 
 OS_NAME 	= $(shell uname -s)
 ST_TARGET 	= linux-debug
@@ -11,9 +12,13 @@ CPU_ARCHS 	+= $(shell g++ -dM -E - </dev/null |grep -q '__aarch64' && echo arm64
 CFLAGS      += -arch $(CPU_ARCHS)
 endif
 
-./pcs:  pcs.c
-	$(CC) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) -Wall -o $@ $^ $(LDLIBS)
+./key: key.c ../tool.h $(LDLIBS)
+	$(CC) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) -Wall -o $@ $< $(LDLIBS)
 
 clean:
-	rm -rf pcs pcs.dSYM
+	cd ../.. && make clean
+	rm -rf key key.dSYM
+
+$(LDLIBS):
+	cd ../.. && make $(ST_TARGET)