Skip to content

Commit e459101

Browse files
tigrannajaryantigrannajaryan
authored
Add stefgen docs (#103)
1 parent 3092df5 commit e459101

File tree

3 files changed

+145
-1
lines changed

3 files changed

+145
-1
lines changed

‎docs/index.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ <h2>Write STEF Records</h2>
9898
<h2>Learn More</h2>
9999
<ul>
100100
<li><a href="https://github.com/splunk/stef/blob/main/stef-spec/specification.md">STEF Specification</a> (detailed format and protocol)</li>
101+
<li><a href="./stefgen.html">Stefgen Code Generator</a> (generate code from STEF schemas)</li>
101102
<li><a href="./benchmarks.html">Benchmarks</a> (performance results)</li>
102103
<li><a href="https://github.com/splunk/stef">GitHub Repository</a></li>
103104
</ul>

‎docs/stefgen.html‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>Stefgen - STEF Code Generator</title>
7+
<link href="https://fonts.googleapis.com/css?family=Roboto:400,700&display=swap" rel="stylesheet">
8+
<link rel="stylesheet" href="./style.css">
9+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/themes/prism.css">
10+
<link rel="stylesheet" href="./prism-stef.css">
11+
</head>
12+
<body>
13+
<header>
14+
<h1>Stefgen</h1>
15+
<nav>
16+
<a href="./index.html">Home</a>
17+
<a href="https://github.com/splunk/stef">GitHub</a>
18+
<a href="https://github.com/splunk/stef/blob/main/stef-spec/specification.md">Specification</a>
19+
</nav>
20+
</header>
21+
<main>
22+
<p><strong>Stefgen</strong> is a command-line code generator that takes STEF schema files as input and generates type-safe serialization and deserialization code for multiple programming languages. It parses STEF schema definitions and produces optimized code that can efficiently read and write STEF-encoded data.</p>
23+
24+
<h2>Installation</h2>
25+
<p>Build stefgen from source:</p>
26+
<pre><code class="language-bash">cd stefgen
27+
make build</code></pre>
28+
<p>This will create the <code>stefgen</code> binary in the <code>bin/</code> directory.</p>
29+
30+
<h2>Usage</h2>
31+
<pre><code class="language-bash">stefgen [flags] &lt;path-to-schema-file&gt;</code></pre>
32+
33+
<h2>Command Line Arguments</h2>
34+
<table>
35+
<thead>
36+
<tr>
37+
<th>Flag</th>
38+
<th>Type</th>
39+
<th>Required</th>
40+
<th>Description</th>
41+
</tr>
42+
</thead>
43+
<tbody>
44+
<tr>
45+
<td><code>-lang</code></td>
46+
<td>string</td>
47+
<td>Yes</td>
48+
<td>Target language for code generation. Supported values: <code>go</code>, <code>java</code></td>
49+
</tr>
50+
<tr>
51+
<td><code>-outdir</code></td>
52+
<td>string</td>
53+
<td>Yes</td>
54+
<td>Output directory where generated source files will be written</td>
55+
</tr>
56+
<tr>
57+
<td><code>-testoutdir</code></td>
58+
<td>string</td>
59+
<td>No</td>
60+
<td>Output directory for test files. If unspecified, defaults to <code>outdir</code>. Only used with <code>-lang=java</code></td>
61+
</tr>
62+
<tr>
63+
<td><code>&lt;schema-file&gt;</code></td>
64+
<td>path</td>
65+
<td>Yes</td>
66+
<td>Path to the STEF schema file (.stef) to process</td>
67+
</tr>
68+
</tbody>
69+
</table>
70+
71+
<h2>Examples</h2>
72+
73+
<h3>Generate Go Code</h3>
74+
<pre><code class="language-bash"># Generate Go code from a STEF schema
75+
stefgen -lang=go -outdir=./generated schema.stef</code></pre>
76+
77+
<h3>Generate Java Code</h3>
78+
<pre><code class="language-bash"># Generate Java code with separate test directory
79+
stefgen -lang=java -outdir=./src/main/java -testoutdir=./src/test/java schema.stef</code></pre>
80+
81+
<h3>Generate Java Code (Simple)</h3>
82+
<pre><code class="language-bash"># Generate Java code with tests in same directory
83+
stefgen -lang=java -outdir=./java-gen schema.stef</code></pre>
84+
85+
<h2>Supported Languages</h2>
86+
<ul>
87+
<li><strong>Go</strong> - Generates Go structs with serialization methods</li>
88+
<li><strong>Java</strong> - Generates Java classes with serialization support</li>
89+
</ul>
90+
91+
<h2>Generated Code Structure</h2>
92+
93+
<p>stefgen creates:</p>
94+
<ul>
95+
<li>Struct, oneof and multimap definitions matching your STEF schema</li>
96+
<li>Type-safe accessors for all fields</li>
97+
<li>Reader for deserialization</li>
98+
<li>Writer for serialization</li>
99+
<li>Read/write unit tests with randomized inputs, matching the schema</li>
100+
</ul>
101+
102+
<h2>Example Workflow</h2>
103+
104+
<h3>1. Define Your Schema</h3>
105+
<p>Create a STEF schema file (e.g., <code>user.stef</code>):</p>
106+
<pre><code class="language-stef">package userdata
107+
108+
struct User root {
109+
Id uint64
110+
Name string
111+
}</code></pre>
112+
113+
<h3>2. Generate Code</h3>
114+
<pre><code class="language-bash">stefgen -lang=go -outdir=./generated user.stef</code></pre>
115+
116+
<h3>3. Use Generated Code</h3>
117+
<p>The generated Go code can then be imported and used in your application:</p>
118+
<pre><code class="language-go">import "github.com/splunk/stef/go/pkg"
119+
import "your-module/generated/userdata"
120+
121+
// Prepare a memory buffer to write the STEF stream to.
122+
buf := &amp;pkg.MemChunkWriter{}
123+
124+
// Create a Writer for the JSON-like schema
125+
w := userdata.NewWriter(buf, pkg.WriterOptions{})
126+
127+
// Build a record in memory.
128+
writer.Record.Value.SetId(1234)
129+
writer.Record.Value.SetName("Foo Bar")
130+
131+
// Write the record to the stream.
132+
writer.Write()
133+
134+
// Flush the stream to the buffer.
135+
writer.Flush()</code></pre>
136+
137+
<p class="footer-note">For more information about STEF schema syntax and features, see the <a href="https://github.com/splunk/stef/blob/main/stef-spec/specification.md">STEF Specification</a>.</p>
138+
</main>
139+
<script src="https://cdn.jsdelivr.net/npm/[email protected]/prism.js"></script>
140+
<script src="https://cdn.jsdelivr.net/npm/[email protected]/components/prism-go.min.js"></script>
141+
<script src="./prism-stef.js"></script>
142+
</body>
143+
</html>

‎makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ all: docs-validate
2828
cd benchmarks && make all
2929

3030
.PHONY: build-ci
31-
build-ci:
31+
build-ci: docs-install-deps docs-validate
3232
cd stefgen && make all
3333
cd go/pkg && make all
3434
cd go/grpc && make

0 commit comments

Comments
 (0)