Merge remote-tracking branch 'origin/topic/robin/doc-guidelines'

* origin/topic/robin/doc-guidelines:
  Docs: Add new section with guidelines and best practices.
  Docs: Update Custom Extensions section.
  Docs: Update feedback section.

CHANGES

@@ -1,3 +1,18 @@
+1.11.0-dev.166 | 2024-05-14 11:54:16 +0200
+
+  * Docs: Add new section with guidelines and best practices. (Robin Sommer, Corelight)
+
+    This focuses on performance for now, but may be extended with other
+    areas alter.
+
+    Much of the content was contributed by Corelight Labs.
+
+  * Docs: Update Custom Extensions section. (Robin Sommer, Corelight)
+
+    The usage of `-P` wasn't up to date.
+
+  * Docs: Update feedback section. (Robin Sommer, Corelight)
+
 1.11.0-dev.162 | 2024-05-13 14:42:08 +0200
 
   * Update types.rst (Smoot)

README.md

@@ -95,9 +95,7 @@ like to hear from you!
 
 - Ask the `#spicy` channel [on Zeek's Slack](https://zeek.org/connect).
 
-- Propose ideas, and show what you're doing, on GitHub's [Discussions](https://github.com/zeek/spicy/discussions).
-
-- Visit the [Zeek community](https://community.zeek.org) to discuss Spicy under
+- Check out the [Zeek community](https://community.zeek.org) and discuss Spicy under
   the [Spicy tag](https://community.zeek.org/c/spicy/).
 
 - To follow development, subscribe to the [commits mailing

VERSION

@@ -1 +1 @@
-1.11.0-dev.162
+1.11.0-dev.166

doc/faq.rst

@@ -41,18 +41,7 @@ Toolchain
 
 .. rubric:: Is there a way to speed up compilation of Spicy code?
 
-Depending on the complexity of the Spicy code, processing through
-``spicyc``/``spicyz``/``spicy-driver`` may take a bit. The bulk of the
-time time tends to be spent on compiling the generated C++ code; often
-about 80-90%. Make sure to run :ref:`spicy-precompile-headers
-<parser-development-setup>` to speed that up a little. During
-development of new parsers, it also helps quite a bit to build
-non-optimized debug versions by adding ``--debug`` to the
-command-line.
-
-If you want to see a break-down of where Spicy spends its time, run
-the tools with ``--report-times``. (In the output at the end, ``jit``
-refers to compiling generated C++ code).
+Please see :ref:`performance_toolchain`.
 
 Zeek
 ----

doc/index.rst

@@ -55,6 +55,7 @@ History
     <https://www.corelight.com>`_, which has contributed the new
     implementation to the Zeek Project.
 
+.. _feedback:
 
 Getting in Touch
 ----------------
@@ -66,10 +67,9 @@ like to hear from you!
 
     - Ask the ``#spicy`` channel on `Zeek's Slack <https://zeek.org/connect>`_.
 
-    - Propose ideas, and show what you're doing, on GitHub's `Discussions <https://github.com/zeek/spicy/discussions>`_.
-
-    - Visit the [Zeek community](https://community.zeek.org) to discuss Spicy under
-      the [Spicy tag](https://community.zeek.org/c/spicy/).
+    - Check out the `Zeek community Discourse
+      <https://community.zeek.org>`_ and discuss Spicy under the
+      `Spicy tag <https://community.zeek.org/c/spicy>`_.
 
     - To follow development, subscribe to the `commits mailing list
       <https://groups.google.com/a/zeek.org/g/spicy-commits/>`_ (it can be

doc/programming/examples/_mylibrary.spicy.output

@@ -1,17 +1,19 @@
-# Automatically generated; do not edit. -- <HASH> spicyc -gP programming/examples/mylibrary.spicy/spicyc -gP mylibrary.spicy/False
-# spicyc -gP mylibrary.spicy
+# Automatically generated; do not edit. -- <HASH> spicyc -P mylib programming/examples/mylibrary.spicy/spicyc -P mylib mylibrary.spicy/False
+# spicyc -P mylib mylibrary.spicy
 // Prototypes for module MyLibrary
 
 #ifndef HILTI_PROTOTYPES_MYLIBRARY_H
 
 #include <hilti/rt/libhilti.h>
 #include <spicy/rt/libspicy.h>
 
+extern const char* __hlt_mylib_hlto_scope;
+
 namespace MyLibrary {
     extern auto rot13(const std::string& s) -> std::string;
 }
 
-namespace __hlt::MyLibrary {
+namespace __hlt_mylib::MyLibrary {
     extern void __register_module();
 }
 

doc/programming/extending.rst

@@ -68,22 +68,17 @@ sides. Internally, Spicy automatically creates a C++ function
 prototype for any function declaration coming with a ``&cxxname``
 attribute. To do so, Spicy maps its own types to corresponding C++
 types. We can see how that looks in  our example by running ``spicyc
--gP`` to print out the generated function prototype (plus a bit of
+-P <prefix>`` to print out the generated function prototype (plus a bit of
 boilerplate to produce a complete C++ ``#include`` header):
 
 .. spicy-output:: mylibrary.spicy
-    :exec: spicyc -gP programming/examples/mylibrary.spicy
-    :show-as: spicyc -gP mylibrary.spicy
+    :exec: spicyc -P mylib programming/examples/mylibrary.spicy
+    :show-as: spicyc -P mylib mylibrary.spicy
 
 As you can see, Spicy maps ``rot13``'s string argument and result into
 ``std::string``, which happens to be exactly what we need in our
-simple example.
-
-.. todo::
-
-    We should tweak ``-P`` so that it disables optimization
-    automatically (because that just removes the supposedly unused
-    function). (:issue:`1284`)
+simple example. (The prefix ``mylib`` goes into some internal IDs to
+avoid nameclashes with other generated code.)
 
 Advanced Usage
 ==============