From 42fc942e1ecf8502bff6d59cf356ee13d62ba21e Mon Sep 17 00:00:00 2001
From: HereThereBeDragons <HereThereBeDragons@users.noreply.github.com>
Date: Fri, 4 Aug 2023 13:16:00 +0200
Subject: [PATCH] CVMFS_SUPPRESS_ASSERTS + source code plugins - as md file

---
 conf.py             |  9 ++++++---
 cpt-quickstart.rst  |  2 ++
 cpt-source-build.md | 34 ++++++++++++++++++++++++++++++++++
 part-advanced.rst   |  1 +
 4 files changed, 43 insertions(+), 3 deletions(-)
 create mode 100644 cpt-source-build.md

diff --git a/conf.py b/conf.py
index 1392ced..0439cd0 100644
--- a/conf.py
+++ b/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'
diff --git a/cpt-quickstart.rst b/cpt-quickstart.rst
index 44117e1..ddc4690 100644
--- a/cpt-quickstart.rst
+++ b/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
 --------------------
 
diff --git a/cpt-source-build.md b/cpt-source-build.md
new file mode 100644
index 0000000..06a680c
--- /dev/null
+++ b/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
+:::
+
diff --git a/part-advanced.rst b/part-advanced.rst
index d776877..685d9ea 100644
--- a/part-advanced.rst
+++ b/part-advanced.rst
@@ -16,3 +16,4 @@ Advanced Topics
    cpt-large-scale
    cpt-shrinkwrap
    cpt-details
+   cpt-source-build
\ No newline at end of file