CVMFS_SUPPRESS_ASSERTS + source code plugins

conf.py

@@ -32,16 +32,19 @@
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinxcontrib.mermaid',
-    'sphinx_rtd_theme'
+    'sphinx_rtd_theme',
+    'myst_parser'
 ]
 
+myst_enable_extensions = ["colon_fence"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'

cpt-quickstart.rst

@@ -181,6 +181,8 @@ Verify the file system
 Check if CernVM-FS mounts the specified repositories by ``cvmfs_config probe``.
 If the probe fails, try to restart autofs with ``sudo systemctl restart autofs``.
 
+.. _sct_building_from_source:
+
 Building from source
 --------------------
 

cpt-source-build.md

@@ -0,0 +1,34 @@
+# Specialized CVMFS Builds from Source
+
+Building CVMFS from source allows personalizing CVMFS further to your needs.
+This can be either due to setting certain build flags or through providing a custom
+source-code plugin.
+
+## Source-Code Plugins
+
+Source-code plugins are plugins you write on your own that please a given interface.
+In some cases, multiple source code plugins might be already made available by CVMFS,
+e.g. there are multiple different cache mangers to choose from, but you can also write
+your own.
+
+| Name                                       | Description                                                                      |
+| ------------------------------------------ | -------------------------------------------------------------------------------- |
+| {ref}`sct_plugin_cache`                    | Write you own cache manager                                                      |
+| {ref}`Telemetry Aggregator<cpt_telemetry>` | Write your own data format how ``cvmfs_talk internal affairs`` is sent to remote |
+
+
+
+
+## Build flags
+
+Build flags must be added to the `cmake`-configure step with `-D <extra-flag>` (see {ref}`sct_building_from_source` for more details).
+
+### `CVMFS_SUPPRESS_ASSERTS`
+-  Replaces certain `asserts` by a logging message instead and has an infinite backoff throttle for `out-of-memory` situations
+-  Affects the client
+-  Useful when the client has a very short TTL for catalogs and runs a lot of updates in parallel and at the same time
+   has a high usage frequency
+:::{warning}
+  This is not a recommended build flag. In very rare cases can the removal of `asserts` lead to undefined client behavior
+:::
+

part-advanced.rst

@@ -16,3 +16,4 @@ Advanced Topics
    cpt-large-scale
    cpt-shrinkwrap
    cpt-details
+   cpt-source-build