From 7b315aed44c466b2149935b87734236472c969f1 Mon Sep 17 00:00:00 2001
From: Runxi Yu <me@runxiyu.org>
Date: Thu, 25 Jul 2024 08:00:00 +0800
Subject: config.md: Write about .makeopts

---
 config.md | 127 +++++++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 96 insertions(+), 31 deletions(-)

(limited to 'config.md')

diff --git a/config.md b/config.md
index 772c1c6..1f0661f 100644
--- a/config.md
+++ b/config.md
@@ -2,35 +2,16 @@
 title: Configuring and Building HaxIRCd
 ---
 
-# `.makeopts`
-```makefile
-LAST_PLAINTEXT_CLIENT = 
-LAST_PLAINTEXT_SERVER = 1
-LAST_GNUTLS_CLIENT = 
-LAST_GNUTLS_SERVER = 
-LAST_OPENSSL_CLIENT = 
-LAST_OPENSSL_SERVER = 1
-LAST_PLAINTEXT_BUFFERED_CLIENT = 
-LAST_PLAINTEXT_BUFFERED_SERVER = 1
-LAST_GNUTLS_BUFFERED_CLIENT = 
-LAST_GNUTLS_BUFFERED_SERVER =   
-LAST_OPENSSL_BUFFERED_CLIENT = 
-LAST_OPENSSL_BUFFERED_SERVER = 1
-LAST_INSPIRCD2_PROTOCOL = 1
-LAST_INSPIRCD3_PROTOCOL = 1
-LAST_INSPIRCD4_PROTOCOL = 1
-LAST_HAXSERV_PSEUDOCLIENT = 1
-LAST_SERVICES_PSEUDOCLIENT = 1
-LAST_SAFE_STACK = 1
-LAST_FUTEX = 1
-LAST_MISERABLE_SPINLOCKS = 
-LAST_ATOMICS = 1
-LAST_IPv6 = 1
-LAST_CFLAGS = 
-LAST_CC = cc
-```
+HaxIRCd does not use an external configuration format. Instead, it is configured
+via [`config.c`](#codeconfigccode), which is just another C source file.
+
+Build options are also significant in determining the behavior of HaxIRCd. Refer
+to the [`.makeopts`](#codemakeoptscode) section for details.
 
 # `config.c`
+This is the main configuration file. When building HaxIRCd, it is built into an
+object file and is linked into the main `HaxIRCd.so` shared object.
+
 ```c
 #include <time.h>
 
@@ -142,14 +123,14 @@ time_t PING_INTERVAL = 60;
 
 #ifdef USE_GNUTLS
 char GNUTLS_USE_SYSTEM_TRUST = 1;
-char *GNUTLS_CERT_PATH = "/etc/letsencrypt/live/learn.tuxiversity.org/fullchain.pem";
-char *GNUTLS_KEY_PATH = "/etc/letsencrypt/live/learn.tuxiversity.org/privkey.pem";
+char *GNUTLS_CERT_PATH = "/path/to/fullchain.pem";
+char *GNUTLS_KEY_PATH = "/path/to/privkey.pem";
 #endif
 
 #ifdef USE_OPENSSL
 char OPENSSL_USE_SYSTEM_TRUST = 1;
-char *OPENSSL_CERT_PATH = "/etc/letsencrypt/live/learn.tuxiversity.org/fullchain.pem";
-char *OPENSSL_KEY_PATH = "/etc/letsencrypt/live/learn.tuxiversity.org/privkey.pem";
+char *OPENSSL_CERT_PATH = "/path/to/fullchain.pem";
+char *OPENSSL_KEY_PATH = "/path/to/privkey.pem";
 #endif
 
 /*
@@ -331,3 +312,87 @@ size_t SERVICES_DB_MAX_SIZE = 104857600;
 struct string SERVICES_DB_PATH = STRING("services.mdb");
 #endif
 ```
+
+# `.makeopts`
+Build options are significant in determining the functionality and behavior
+of HaxIRCd. You may specify build options in a `.makeopts` file, such as
+the following:
+
+```makefile
+# The following options control which network transports are built into
+# HaxIRCd.
+# PLAINTEXT: Use plain TCP sockets.
+# GNUTLS:    Use TLS over TCP, as provided by GnuTLS.
+# OPENSSL:   Use TLS over TCP, as provided by OpenSSL/LibreSSL.
+# SERVER:    Support using this transport in S2S connections.
+# CLIENT:    Support using this transport in S2C connections.
+# The BUFFERED variants causes sending to occur over a separate thread
+# and uses a ring buffer to buffer messages, until full messages are
+# ready to send. These usually perform better than their unbuffered
+# counterparts. The size of the ring buffer is configurable in
+# config.c.
+LAST_PLAINTEXT_CLIENT = 1
+LAST_PLAINTEXT_SERVER = 1
+LAST_GNUTLS_CLIENT = 
+LAST_GNUTLS_SERVER = 
+LAST_OPENSSL_CLIENT = 1
+LAST_OPENSSL_SERVER = 1
+LAST_PLAINTEXT_BUFFERED_CLIENT = 1
+LAST_PLAINTEXT_BUFFERED_SERVER = 1
+LAST_GNUTLS_BUFFERED_CLIENT = 
+LAST_GNUTLS_BUFFERED_SERVER =   
+LAST_OPENSSL_BUFFERED_CLIENT = 1
+LAST_OPENSSL_BUFFERED_SERVER = 1
+
+# The following control the server protocols compiled into HaxIRCd.
+# You should enable at least one of them. Note that InspIRCd v(n+1) is
+# compatible with INSPIRCD(n)_PROTOCOL.
+LAST_INSPIRCD2_PROTOCOL = 1
+LAST_INSPIRCD3_PROTOCOL = 1
+LAST_INSPIRCD4_PROTOCOL = 1
+
+# The following control pseudoclients compiled into HaxIRCd.
+LAST_HAXSERV_PSEUDOCLIENT = 1
+LAST_SERVICES_PSEUDOCLIENT = 1
+
+# When SAFE_STACK is enabled, -fstack-check is added to CFLAGS.
+LAST_SAFE_STACK = 1
+
+# The following control how locks are handled in HaxIRCd.
+# ATOMICS are recommended whenever supported. FUTEX is recommended on Linux.
+# MISERABLE_SPINLOCKS may be used on systems that support neither POSIX
+# semaphores or futexes. If neither FUTEX or MISERABLE_SPINLOCKS are
+# defined, POSIX semaphores are used.
+LAST_FUTEX = 1
+LAST_MISERABLE_SPINLOCKS = 
+LAST_ATOMICS = 1
+
+# Should HaxIRCd support IPv6? If it is possible that getaddrinfo(3)
+# returns an IPv6 address, or if an IPv6 address is specified directly,
+# then IPv6 MUST be enabled; otherwise the behavior is undefined.
+LAST_IPv6 = 1
+
+# General optoins.
+LAST_CFLAGS = 
+LAST_CC = cc
+```
+
+You may also change individual paramters by passing arguments to Make. For
+example, to enable IPv6 and InspIRCd v3 protocol support in the current build
+and all future builds:
+
+```sh
+make IPv6=1 INSPIRCD3_PROTOCOL=1
+```
+
+# Building
+
+```sh
+make
+```
+
+# Running
+
+```sh
+./HaxIRCd
+```
-- 
cgit v1.2.3