Merge pull request #76 from vibe-d/docs_cleanup

Documentation maintainance
vibe-d · Apr 12, 2024 · 0234e66 · 0234e66
2 parents 0a87fb4 + 67859ba
commit 0234e66
Show file tree

Hide file tree

Showing 4 changed files with 105 additions and 69 deletions.
diff --git a/dub.sdl b/dub.sdl
@@ -1,9 +1,9 @@
 name "vibed-org"
 description "The official vibe.d website."
-copyright "Copyright © 2012-2017 rejectedsoftware e.K."
+copyright "Copyright © 2012-2024 Sönke Ludwig"
 license "AGPL-3.0"
 
-dependency "vibe-d" version=">=0.8.3 <0.10.0-0"
+dependency "vibe-d" version=">=0.10.0 <0.11.0-0"
 dependency "ddox" version="~>0.16.0"
 dependency "diet-ng" version="~>1.2"
 dependency "vibelog" version="~>0.6.0"

diff --git a/dub.selections.json b/dub.selections.json
@@ -1,25 +1,30 @@
 {
 	"fileVersion": 1,
 	"versions": {
-		"antispam": "0.1.6",
-		"ddox": "0.16.22",
+		"antispam": "0.1.7",
+		"ddox": "0.16.23",
 		"diet-ng": "1.8.1",
-		"diskuto": "1.7.3",
-		"eventcore": "0.9.25",
+		"diskuto": "1.7.6",
+		"eventcore": "0.9.28",
 		"fuzzydate": "1.0.0",
 		"hyphenate": "1.1.4",
 		"libasync": "0.8.6",
 		"libdparse": "0.15.4",
-		"memutils": "1.0.9",
+		"memutils": "1.0.10",
 		"mir-linux-kernel": "1.0.1",
-		"openssl": "3.3.2",
+		"openssl": "3.3.3",
 		"openssl-static": "1.0.2+3.0.8",
-		"rs-bootstrap": "1.0.5",
+		"rs-bootstrap": "1.0.6",
 		"stdx-allocator": "2.77.5",
 		"stringex": "0.1.1",
 		"taggedalgebraic": "0.11.22",
-		"vibe-core": "2.2.0",
-		"vibe-d": "0.9.7",
-		"vibelog": "0.6.11"
+		"vibe-container": "1.3.0",
+		"vibe-core": "2.8.2",
+		"vibe-d": "0.10.0",
+		"vibe-http": "1.0.0",
+		"vibe-inet": "1.0.0",
+		"vibe-serialization": "1.0.1",
+		"vibe-stream": "1.1.0",
+		"vibelog": "0.6.12"
 	}
 }
diff --git a/views/docs.dt b/views/docs.dt
@@ -46,6 +46,7 @@ block vibed.navigation
 				li: a(href="#dub-publishing") Publishing on the DUB registry
 				li: a(href="#custom-main") The main function
 				li: a(href="#privilege-lowering") Privilege lowering
+				li: a(href="#event-loop-driver") Selecting the event loop driver
 				li: a(href="#compile-time-configuration") Compile time configuration
 				li: a(href="#handling-segmentation-faults") Handling segmentation faults on Linux
 		li.bs-separator: a(href="templates/diet") Diet Reference
@@ -57,7 +58,7 @@ block vibed.body
 
 		p First, install the <a href="https://github.com/dlang/dub">DUB package manager</a> to let it handle downloading and building of vibe.d and derived applications. On non-Windows systems, a number of additional dependencies needs to be installed. See the <a href="https://github.com/vibe-d/vibe.d#installation">project description on GitHub</a> for details.
 
-		p Manual building (e.g. using RDMD) is a possible alternative, but you have to make sure that external libraries are linked in (such as libevent) and that a version identifier for the used driver is passed to the compiler (e.g. <code>-version=VibeLibeventDriver</code>). Take a look at <a href="https://github.com/vibe-d/vibe.d/blob/master/dub.sdl">vibe.d's dub.sdl</a> to determine how to build on a certain platform, or, alterntaively, run DUB with the <code>-v</code> switch to see the actual compiler command line.
+		p Manual building (e.g. using RDMD) is a possible alternative, but you have to make sure that external libraries are linked in (such as OpenSSL) and that the import directories for all sub projects of vibe.d (such as vibe-core and vibe-http) are properly set. You can run DUB with the <code>-v</code> switch to see the actual compiler command line if in doubt.
 
 		p The easiest way to get started is to run the following command from your projects directory:
 
@@ -71,32 +72,31 @@ block vibed.body
 		pre.code.
 			cd path/to/project
 			dub
-			<span class="com">Performing "debug" build using dmd for x86_64.
-			Performing "debug" build using ldc2 for x86_64.
-			taggedalgebraic 0.11.8: target for configuration "library" is up to date.
-			eventcore 0.8.48: target for configuration "winapi" is up to date.
-			stdx-allocator 2.77.5: target for configuration "library" is up to date.
-			vibe-core 1.8.0: target for configuration "winapi" is up to date.
-			vibe-d:utils 0.8.6: target for configuration "library" is up to date.
-			vibe-d:data 0.8.6: target for configuration "library" is up to date.
-			mir-linux-kernel 1.0.1: target for configuration "library" is up to date.
-			vibe-d:crypto 0.8.6: target for configuration "library" is up to date.
-			diet-ng 1.6.0+commit.10.g6032ae1: target for configuration "library" is up to date.
-			vibe-d:stream 0.8.6: target for configuration "library" is up to date.
-			vibe-d:textfilter 0.8.6: target for configuration "library" is up to date.
-			vibe-d:inet 0.8.6: target for configuration "library" is up to date.
-			vibe-d:tls 0.8.6: target for configuration "openssl-mscoff" is up to date.
-			vibe-d:http 0.8.6: target for configuration "library" is up to date.
-			vibe-d:mail 0.8.6: target for configuration "library" is up to date.
-			vibe-d:mongodb 0.8.6: target for configuration "library" is up to date.
-			vibe-d:redis 0.8.6: target for configuration "library" is up to date.
-			vibe-d:web 0.8.6: target for configuration "library" is up to date.
-			vibe-d 0.8.6: target for configuration "vibe-core" is up to date.
-			vibe-test ~master: building configuration "application"...
-			Linking...
-			To force a rebuild of up-to-date targets, run again with --force.
-			Copying files for vibe-d:tls...
-			Running .\vibe-test.exe
+			<span class="com">    Starting Performing "debug" build using ldc2 for x86_64.
+			  Up-to-date diet-ng 1.8.1: building configuration [library]
+			  Up-to-date taggedalgebraic 0.11.22: building configuration [library]
+			  Up-to-date eventcore 0.9.28: building configuration [winapi]
+			  Up-to-date vibe-container 1.3.0: building configuration [library]
+			  Up-to-date vibe-core 2.8.2: building configuration [winapi]
+			  Up-to-date vibe-inet:textfilter 1.0.0: building configuration [library]
+			  Up-to-date vibe-serialization 1.0.1: building configuration [library]
+			  Up-to-date vibe-stream 1.1.0: building configuration [library]
+			  Up-to-date vibe-inet 1.0.0: building configuration [library]
+			  Up-to-date mir-linux-kernel 1.0.1: building configuration [library]
+			  Up-to-date vibe-inet:crypto 1.0.0: building configuration [library]
+			  Up-to-date vibe-stream:tls 1.1.0: target for configuration [openssl-3.0] is up to date.
+			  Up-to-date vibe-http 1.0.0: building configuration [library]
+			  Up-to-date vibe-d:mail 0.10.0: building configuration [library]
+			  Up-to-date vibe-d:mongodb 0.10.0: building configuration [library]
+			  Up-to-date vibe-d:redis 0.10.0: building configuration [library]
+			  Up-to-date vibe-d:utils 0.10.0: building configuration [library]
+			  Up-to-date vibe-d:web 0.10.0: building configuration [library]
+			  Up-to-date vibe-d 0.10.0: building configuration [library]
+			    Building vibe-test ~master: building configuration [application]
+			     Linking vibe-test
+			    Finished To force a rebuild of up-to-date targets, run again with --force
+			             Copying files for vibe-stream:tls...
+			     Running vibe-test.exe
 			[main(----) INF] Listening for requests on http://[::1]:8080/
 			[main(----) INF] Listening for requests on http://127.0.0.1:8080/
 			[main(----) INF] Please open http://127.0.0.1:8080/ in your browser.</span>
@@ -115,7 +115,7 @@ block vibed.body
 				views/
 					layout.dt
 					index.dt
-				dub.json
+				dub.sdl
 		.caption Example structure of a web application project
 
 		p For a simple web application, the 'app.d' file could look similar to this one:
@@ -172,7 +172,7 @@ block vibed.body
 			license "AGPL-3.0"
 			homepage "http://appname.org"
 			authors "Hans Wurst"
-			dependency "vibe-d" version="~&gt;0.8.6"
+			dependency "vibe-d" version="~&gt;0.10.0"
 		.caption Example dub.sdl
 
 		p DUB also provides support for the original JSON based syntax. The filename to use is "dub.json" in this case:
@@ -185,7 +185,7 @@ block vibed.body
 				"homepage": "http://appname.org",
 				"authors": ["Hans Wurst"],
 				"dependencies": {
-					"vibe-d": "~&gt;0.8.6"
+					"vibe-d": "~&gt;0.10.0"
 				}
 			}
 		.caption Example dub.json
@@ -260,22 +260,22 @@ block vibed.body
 
 			h4 Selecting the TLS provider
 
-			p Two TLS providers are currently supported, OpenSSL and the D port of Botan. By default, OpenSSL 1.0.x is used to provide TLS/HTTPS functionality. To select a different provider, or to avoid compiling with TLS support enabled, the appropriate build configuration of the vibe-d:tls sub package needs to be selected:
+			p Two TLS providers are currently supported, OpenSSL and the D port of Botan. By default, OpenSSL 3.x is used to provide TLS/HTTPS functionality. To select a different provider, or to avoid compiling with TLS support enabled, the appropriate build configuration of the vibe-d:tls sub package needs to be selected:
 			pre.code.prettyprint.lang-sdl.
-				dependency "vibe-d:tls" version="*"
-				subConfiguration "vibe-d:tls" "botan"
+				dependency "vibe-stream:tls" version="~>1.0"
+				subConfiguration "vibe-stream:tls" "botan"
 
 			p When using a JSON based package recipe, the two lines have to be inserted as follows (the "&hellip;" are just placeholders for other possible directives):
 			pre.code.prettyprint.lang-json.
 				{
 					&hellip;
 					"dependencies": {
 						&hellip;
-						"vibe-d:tls": "*"
+						"vibe-stream:tls": "~>1.0"
 					},
 					"subConfigurations": {
 						&hellip;
-						"vibe-d:tls": "botan"
+						"vibe-stream:tls": "botan"
 					}
 				}
 
@@ -284,11 +284,15 @@ block vibed.body
 					dt: code "notls"
 					dd Don't compile with TLS support
 					dt: code "openssl"
-					dd OpenSSL 1.0.x (default)
+					dd OpenSSL, auto-detect version (default)
+					dt: code "openssl-3.0"
+					dd OpenSSL 3.0.x (default in Windows)
 					dt: code "openssl-1.1"
 					dd OpenSSL 1.1.x
-					dt: code "openssl-0.9"
-					dd OpenSSL 0.9.8
+					dt: code "openssl-1.0"
+					dd OpenSSL 1.0.x
+					dt: code "openssl-static"
+					dd Uses the openssl-static package to provide static OpenSSL 3.x binaries on various platforms
 					dt: code "botan"
 					dd D port of Botan
 
@@ -852,7 +856,7 @@ block vibed.body
 						"Sönke Ludwig"
 					],
 					"dependencies": {
-						"vibe-d": "~&gt;0.7.23"
+						"vibe-d": "~&gt;0.10.0"
 					}
 				}
 			.caption Example: A dub.json file suitable for registration as a DUB package.
@@ -914,6 +918,49 @@ block vibed.body
 				}
 			.caption Example vibe.conf file
 
+		section
+			h3#event-loop-driver Selecting the event loop driver
+
+			p By default, the native API for each platform is selected as the default for providing the asynchronous I/O and concurrency primitive support. However, you may select a particular implementation if there are more than one available for the target platform. In order to override the default, add a sub configuration directive to your dub.sdl (choosing the "select" driver in this case):
+
+			pre.code.prettyprint.lang-sdl.
+				dependency "eventcore" version="*"
+				subConfiguration "eventcore" "select"
+
+			p When using a JSON based package recipe, the two lines have to be inserted as follows (the "&hellip;" are just placeholders for other possible directives):
+			pre.code.prettyprint.lang-json.
+				{
+					&hellip;
+					"dependencies": {
+						&hellip;
+						"eventcore": "*"
+					},
+					"subConfigurations": {
+						&hellip;
+						"eventcore": "select"
+					}
+				}
+
+			p The following implementations are available:
+
+			dl
+				dt: code "epoll"
+				dd Uses the Linux <code>epoll</code> interface, default when building for Linux, including Android
+				dt: code "epoll-gaia"
+				dd Uses the Linux <code>epoll</code> interface and <code>getaddrinfo_a</code> for asynchronous DNS lookups
+				dt: code "cfrunloop"
+				dd On Darwin based systems (macOS/iOS), uses <code>CFRunLoop</code> in order to be compatible with GUI applications, default on macOS and iOS
+				dt: code "kqueue"
+				dd Uses the BSD <code>kqueue</code> interface, default on FreeBSD, also available on Darwin based systems
+				dt: code "winapi"
+				dd Windows API based implementation using <code>MsgWaitForMultipleObjectsEx</code> in order to be compatible with GUI applications, default on Windows
+				dt: code "select"
+				dd Available for all Posix compliant systems, as well as Windows, uses <code>select()</code> for non-blocking I/O, only recommended for otherwise unsupported platforms
+				dt: code "libasync"
+				dd Uses the libasync library to choose and wrap the operating system specific API
+				dt: code "generic"
+				dd Does not provide a driver, but instead requires calling <code>setupEventDriver</code> to set a custom driver implementation
+
 		section
 			h3#compile-time-configuration Compile time configuration
 
@@ -973,7 +1020,7 @@ block vibed.body
 
 				tr
 					td: code VibePragmaLib
-					td Uses a <code>pragma(lib)</code> to link against OpenSSL and libevent. This is only useful for building without DUB.
+					td Uses a <code>pragma(lib)</code> to link against OpenSSL. This is only useful for building without DUB.
 
 				tr
 					td: code: del VibeCustomMain
@@ -991,22 +1038,6 @@ block vibed.body
 					td: code: del VibeUseOldOpenSSL
 					td #[del Disables the use of features introduced in OpenSSL 1.0.1 or later, most notably ECDH curve selection. Use this to link against old versions of the OpenSSL library.] Deprecated for 0.8.0 and up, see the #[a(href="#http-https") HTTPS section] instead
 
-				tr
-					td: code: del VibeLibevDriver
-					td #[del Enables the libev based event driver (not fully functional).] This driver has been removed.
-
-				tr
-					td: code: del VibeLibeventDriver
-					td #[del Enables the libevent based event driver (currently the default).] Do not use this version directly, but select the "libevent" configuration in your dub.json instead.
-
-				tr
-					td: code: del VibeWin32Driver
-					td #[del Enables the Win32 based event driver (provides GUI message support on Windows).] Do not use this version directly, but select the "win32" configuration in your dub.json instead.
-
-				tr
-					td: code: del VibeWinrtDriver
-					td #[del Enables the WinRT based event driver (not yet implemented).] This driver has been removed
-
 
 		section
 			h3#handling-segmentation-faults Handling segmentation-faults on Linux

diff --git a/views/features.dt b/views/features.dt
@@ -127,7 +127,7 @@ block vibed.body
 			h3#aio Asynchronous I/O operations
 			img.leftFlow(src="images/feature_event.png")
 
-			p Instead of using classic blocking I/O together with multi-threading for doing parallel network and file operations, all operations are using asynchronous operating system APIs. By default, <a class="extern" href="https://libevent.org/" target="_blank">libevent</a> is used to access these APIs operating system independently.
+			p Instead of using classic blocking I/O together with multi-threading for doing parallel network and file operations, all operations are using asynchronous operating system APIs. #[a.extern(href="https://github.com/vibe-d/eventcore/", target="_blank") eventcore] is used to access these APIs operating system independently.
 
 			p Using asynchronous I/O has several advantages, the main point being that the memory overhead is much lower. This is because only a single hardware thread is needed to handle an arbitrary number of concurrent operations. The thread typically rests waiting for events and is woken up by the operating system as soon as new data arrives, a new connection is established, or an error occurs. After each initiated blocking operation (e.g. writing data to a socket), the thread will go back to sleep and let the operating system execute the operation in the background.