Merge branch 'dev' of github.com:brainboxdotcc/DPP

.github/PULL_REQUEST_TEMPLATE/docs_change_template.md

@@ -2,7 +2,7 @@
 
 ## Documentation change checklist
 
-- [ ] My documentation changes follow the same style as the rest of the documentation and any examples follow the [coding style guide](https://dpp.dev/coding-standards.html).
+- [ ] My documentation changes follow the [docs style guide](https://dpp.dev/docs_standards.html) and any code examples follow the [coding style guide](https://dpp.dev/coding-standards.html).
 - [ ] I tested that my change works before raising the PR (via running `doxygen`, and testing examples).
 - [ ] I have not moved any existing pages or changed any existing URLs without strong justification as to why.
 - [ ] I have not generated content using AI or a desktop utility such as grammarly.

.github/workflows/ci.yml

@@ -60,7 +60,7 @@ jobs:
         run: cd build && make -j2
 
       - name: Run unit tests
-        run: cd build/library && ./unittest
+        run: cd build && ctest -VV
         env:
           DPP_UNIT_TEST_TOKEN: ${{secrets.DPP_UNIT_TEST_TOKEN}}
           TEST_GUILD_ID: ${{secrets.TEST_GUILD_ID}}
@@ -133,8 +133,15 @@ jobs:
   macos:
     permissions:
       contents: write
-    name: macOS x64
-    runs-on: macos-latest
+    name: macOS ${{matrix.cfg.arch}} (${{matrix.cfg.cpp-version}})
+    runs-on: ${{matrix.cfg.os}}
+    strategy:
+      fail-fast: false # Don't fail everything if one fails. We want to test each OS/Compiler individually
+      matrix:
+        # arm64 is a self-hosted runner on a Mac M2 Mini, ran inside a virtual machine by Archie Jaskowicz.
+        cfg:
+          - { arch: 'x64', concurrency: 3, os: macos-latest, cpp-version: clang++-14, cmake-flags: '', cpack: 'no' }
+          - { arch: 'arm64', concurrency: 2, os: [self-hosted, ARM64, macOS], cpp-version: clang++-15, cmake-flags: '', cpack: 'no' }
     steps:
       - name: Harden Runner
         uses: step-security/harden-runner@1b05615854632b887b69ae1be8cbefe72d3ae423 # v2.6.0
@@ -145,18 +152,21 @@ jobs:
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Install homebrew packages
-        run: brew install cmake make libsodium opus openssl
+        run: brew install cmake make libsodium opus openssl pkg-config
 
       - name: Generate CMake
         run: mkdir build && cd build && cmake -DDPP_NO_VCPKG=ON -DCMAKE_BUILD_TYPE=Release -DDPP_CORO=ON -DAVX_TYPE=AVX0 ..
         env:
           DONT_RUN_VCPKG: true
 
       - name: Build Project
-        run: cd build && make -j3
+        run: cd build && make -j${{ matrix.cfg.concurrency }}
         env:
           DONT_RUN_VCPKG: true
 
+      - name: Run offline unit tests
+        run: cd build && ctest -VV
+
   windows: # Windows x64 and x86 build matrix
     permissions:
       contents: write

.gitignore

@@ -30,3 +30,4 @@ config.json
 .misspell-fixer.ignore
 compile_commands.json
 src/dpp/dpp.rc
+.DS_STORE

CMakeLists.txt

@@ -69,6 +69,12 @@ if (NOT DPP_NO_VCPKG AND EXISTS "${_VCPKG_ROOT_DIR}")
 		HOMEPAGE_URL "https://dpp.dev/"
 		DESCRIPTION "An incredibly lightweight C++ Discord library."
 	)
+
+	# Required before we add any subdirectories.
+	if (DPP_BUILD_TEST)
+		enable_testing(${CMAKE_CURRENT_SOURCE_DIR})
+	endif()
+
 	add_subdirectory(library-vcpkg)
 else()
 	set(PROJECT_NAME "libdpp")
@@ -79,6 +85,12 @@ else()
 		HOMEPAGE_URL "https://dpp.dev/"
 		DESCRIPTION "An incredibly lightweight C++ Discord library."
 	)
+
+	# Required before we add any subdirectories.
+	if (DPP_BUILD_TEST)
+		enable_testing(${CMAKE_CURRENT_SOURCE_DIR})
+	endif()
+
 	add_subdirectory(library)
 endif()
 

README.md

@@ -79,9 +79,9 @@ You can find more examples in our [example page](https://dpp.dev/example-program
 
 The library runs ideally on **Linux**.
 
-### Mac OS X and FreeBSD and OpenBSD
+### Mac OS X, FreeBSD, and OpenBSD
 
-The library is well-functional and stable on **Mac OS X**, **FreeBSD**, and **OpenBSD** too.
+The library is well-functional and stable on **Mac OS X**, **FreeBSD**, and **OpenBSD** too!
 
 ### Raspberry Pi
 

buildtools/emojis.php

@@ -12,9 +12,11 @@
 namespace dpp {
 
 /**
- * The unicode emojis in this namespace are auto-generated from {$url}
+ * @brief Emoji unicodes.
  *
- * If you want to use this, you have to pull the header in separately. e.g.
+ * @note The unicode emojis in this namespace are auto-generated from https://raw.githubusercontent.com/ArkinSolomon/discord-emoji-converter/master/emojis.json
+ *
+ * @warning If you want to use this, you have to pull the header in separately. For example:
  * ```cpp
  * #include <dpp/dpp.h>
  * #include <dpp/unicode_emoji.h>

docpages/06_advanced_reference.md

@@ -4,6 +4,7 @@
 * \subpage thread-model
 * \subpage voice-model
 * \subpage coding-standards
+* \subpage docs-standards
 * \subpage unit-tests
 * \subpage lambdas-and-locals
 * \subpage governance

docpages/INDEX.md

@@ -48,8 +48,8 @@ You can find further releases in other architectures and formats or the source c
 ### Linux
 The library runs ideally on **Linux**.
 
-### Mac OS X and FreeBSD
-The library is well-functional and stable on **Mac OS X** and **FreeBSD** too.
+### Mac OS X, FreeBSD, and OpenBSD
+The library is well-functional and stable on **Mac OS X**, **FreeBSD**, and **OpenBSD** too!
 
 ### Raspberry Pi
 For running your bot on a **Raspberry Pi**, we offer a prebuilt .deb package for ARM64, ARM6, and ARM7 so that you do not have to wait for it to compile.
@@ -63,10 +63,10 @@ The library should work fine on other operating systems as well, and if you run
 ## Getting started
 * [GitHub Repository](https://github.com/brainboxdotcc/DPP)
 * [Discord Server](https://discord.gg/dpp)
-* \ref frequently-asked-questions "Frequently Asked Questions"
-* \ref installing "Installing D++"
-* \ref example-programs "Example Programs"
-* \ref glossary-of-common-discord-terms "Commonly used terms"
+* \ref frequently-asked-questions
+* \ref installing
+* \ref example-programs
+* \ref glossary-of-common-discord-terms
 
 ## Architecture
 * \ref clusters-shards-guilds

docpages/advanced_reference/docs-style-standards.md

@@ -0,0 +1,84 @@
+\page docs-standards Documentation Style Standards
+
+This page lists the documentation standards that you must follow when making PRs for files in `docpages`, this does not mean documentation for functions/variables inside actual code. If something is not covered here, ask on the [official Discord server](https://discord.gg/dpp)!
+
+Please also follow the \ref coding-standards for your PRs related to docs. This covers any code stuff that you may end up writing along with other stuff (for example, conventional commits).
+
+## Adding Pages
+
+All pages should start off with `\ page <page_name> <page title>`, with the space between `\` and `page` removed.
+
+Adding a new page requires you to also add the page as a subpage to a section. For example, if you're creating a new page under "The Basics", you should edit "the_basics.md" inside "example_programs" and add your page as a subpage.
+
+All subpages should be added like so: `* \ subpage <page_name>`, with the space between `\` and `subpage` removed.
+
+## Page and File Names
+
+The naming convention for page and file names are `kebab-case`, so you should name pages and files something like `name-of-page`, with `.md` added to the end of the file name.
+
+However, code files should be `snake_case` to follow the \ref coding-standards. Images follow the same format.
+
+\note There are pages that do not follow this format, **please do not change them**. This is explained in the **Renaming Files** section.
+
+## Page Titles
+
+Page titles shouldn't be mistaken with page names! Page titles are the, sometimes, long-ish titles you see in the navbar on the left of the docs page or at the top of each page when you view it in a web browser. Try not to make these too long (80 chars is the max limit but reach for less) as it's a bit daunting seeing a long title!
+
+## Renaming Files
+
+Renaming `.md` files is something that shouldn't really be done unless you have a very good reason. Changing it harms our SEO, meaning google will get a bit confused.
+
+Changing images in the `images` folder or files inside the `example_code` folder is more acceptable, however, still shouldn't be done without reason.
+
+## Referencing Other Pages
+
+Pages located within our file structure should be referenced like `\ ref <page_name>` (this will insert a reference with the actual page title) or `\ ref <page_name> "text here"` (instead of the page title, it'll be whatever is in quotation marks), with the space between `\` and `ref` removed. Pages outside of our file structure (like a discord invite link, or a github page, etc) should be referenced like `[text](url)`.
+
+## Adding Code to Examples
+
+All code needs to be a `.cpp` file in the `example_code` folder. You then reference it via `\ include{cpp} file.cpp`, with the space between `\` and `include{cpp}` removed.
+
+Any code that will **not** build, for example:
+```cpp
+bot.start(dpp::st_wait);
+/* This code will not build as it has no entry (int main), which will cause CI fails. */
+```
+should be placed in the file itself. This is so we do not have to worry about the CI testing your example when we know it will not work.
+
+## Language (Not Programming)
+
+Your text and images should be in English.
+
+## Images
+
+Images are a great way to show people what they can expect at the end, a lot of tutorials don't have them but don't feel like you can't add any! We ask that you don't add images that are inappropriate and only add them if they make sense. Cut them down to a size that is readable and make sure it only contains information that is needed, for example, we don't need to see your server's channels list if the tutorial isn't covering it!
+
+Take a look at some tutorial pages (for example, \ref embed-message and \ref callback-functions) to understand what we mean.
+
+All your images should be placed in the `images` folder and should be named similar to your page's name. If you have multiple images, you can either do something like `image_name2`, `image_name3`, and so on. You can also give them unique names like `image_name_overview`, `image_name_end`, and so on.
+
+## Grammar and Spelling
+
+Your spelling and grammar matters a lot, it's essential that you get it right. We do have a GitHub Action runner that may flag for incorrect spellings if you accidentally spell something incorrectly (We're all human!), so keep an eye out for that. If this falsely flags you, read the \ref coding-standards page for more information about how to tell it to ignore a word.
+
+## Consistency
+
+Try to match other pages if you are making a similar guide (for example, the building from source pages). If the pages are inconsistent, they will start to confuse people. This also goes for pages that may not even be similar! For example, you should try keep your code examples similar to others, so that people don't get confused and can easily follow along.
+
+## Being Simplistic
+
+As you'll be writing tutorials, try be simplistic! Don't overcomplicate pages and don't make assumptions that, just because you know it, everyone else will, because some people may not know what you're talking about! An easy, yet informational, tutorial is key to ensuring that D++ has great documentation for newcomers.
+
+## AI and Desktop Utilities
+
+We are strongly against the use of AI within any part of code and docs. AI can be unreliable and may give the wrong information, so please look to research and test what you're documenting, without the use of AI. If we feel your entire PR was wrote by AI, we will close the PR.
+
+We also advise you do not use grammarly or other tools that fix your grammar/spelling for you. They can mess with text, get it wrong, not understand the context, etc. Whilst you can certainly use spell checkers and/or tools to see if there's issues with your text, you should look over each issue yourself to make sure if it matches the context and the issue is actually correct.
+
+## Testing Your Changes
+
+To test your commits, you should install `doxygen` and `graphviz`. Then, inside your DPP folder, run `doxygen`. This will start generating a bunch of files inside a `docs` folder and may take a while. After that, view the .md file in your web browser.
+
+If this seems to fail, you can make your PR draft and use the netlify bot that replies with a link (the link may take a bit to generate) to preview your changes.
+
+If you are adding code with your commits, you **need** to test it with a bot. Our CI will test it too, but we expect that you at least test it on your end.

docpages/building/linux.md

@@ -2,9 +2,10 @@
 
 \note You might not need to build a copy of the library for Linux - precompiled deb files for 64 bit and 32 bit Debian and Ubuntu are provided in the GitHub version releases. Unless you are on a different Linux distribution which does not support the installation of deb files, or wish to submit fixes and enhancements to the library itself you should have an easier time installing the precompiled version instead.
 
-## 1. Build Source Code
-
+## 1. Copy & Build Source code
 ```bash
+git clone https://github.com/brainboxdotcc/DPP
+cd DPP/
 cmake -B ./build
 cmake --build ./build -j8
 ```
@@ -23,7 +24,7 @@ sudo make install
 If you want to install the library, its dependencies, and header files to a different directory, specify this directory when running `cmake`:
 
 ```bash
-cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install
+cmake -B ./build -DCMAKE_INSTALL_PREFIX=/path/to/install
 ```
 
 Then once the build is complete, run `make install` to install to the location you specified.
@@ -36,12 +37,27 @@ Once installed to the `/usr/local` directory, you can make use of the library in
 g++ -std=c++17 mydppbot.cpp -o dppbot -ldpp
 ```
 
+If you are on **Arch Linux**, you will need to add `/usr/local` to your environment variables:
+
+```bash
+export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
+export CPLUS_INCLUDE_PATH=/usr/local/include:$CPLUS_INCLUDE_PATH
+```
+
+However, if you don't want to change your environment settings, you can use these flags to compile:
+
+```bash
+g++ -std=c++17 -L/usr/local/lib -I/usr/local/include mydppbot.cpp -o dppbot -ldpp
+```
+
 The important flags in this command-line are:
 
 * `-std=c++17` - Required to compile the headers
-* `-ldpp` - Link to libdpp.so
+* `-L/usr/local/lib` - Required to tell the linker where libdpp is located.
+* `-I/usr/local/include` - Required to tell the linker where dpp headers are located.
 * `mydppbot.cpp` - Your source code
 * `dppbot` - The name of the executable to make
+* `-ldpp` - Link to libdpp.so
 
 \include{doc} install_prebuilt_footer.dox
 

docpages/building/osx.md

@@ -10,9 +10,11 @@ Before compiling make sure you have all the tools installed.
 ## 2. Install External Dependencies
 
 ```bash
-brew install openssl
+brew install openssl pkgconfig
 ```
 
+\note Usually, you do not need pkgconfig. However, it seems that it throws errors about openssl without.
+
 For voice support, additional dependencies are required:
 
 ```bash
@@ -43,7 +45,7 @@ If you want to install the library, its dependencies, and header files to a diff
 cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install
 ```
 
-Then once the build is complete, run `make install` to install to the location you specified.
+Then once the build is complete, run `sudo make install` to install to the location you specified.
 
 ## 6. Using the Library
 

docpages/example_code/clearing_slashcommands.cpp

@@ -1,7 +1,6 @@
 #include <dpp/dpp.h>
 
-int main()
-{
+int main() {
 	dpp::cluster bot("token");
 
 	bot.on_log(dpp::utility::cout_logger());
@@ -12,7 +11,7 @@ int main()
 		if (dpp::run_once<struct clear_bot_commands>()) {
 			/* Now, we're going to wipe our commands */
 			bot.global_bulk_command_delete();
-			/* This one requires a guild id, otherwise it won't what guild's commands it needs to wipe! */
+			/* This one requires a guild id, otherwise it won't know what guild's commands it needs to wipe! */
 			bot.guild_bulk_command_delete(857692897221033129);
 		}
 

docpages/example_programs/the_basics/firstbot.md

@@ -100,7 +100,7 @@ The `event.reply` function (dpp::slashcommand_t::reply) replies to a slash comma
 
 To make the bot start, we must call the dpp::cluster::start method, e.g. in our program by using `bot.start(dpp::st_wait)`.
 
-We also add a line to tell the library to output all its log information to the console, `bot.on_log(dpp::utility::cout_logger());` - if you wanted to do something more advanced, you can replace this parameter with a lambda just like all other events.
+We also add a line to tell the library to output all its log information to the console, use `bot.on_log(dpp::utility::cout_logger());` (dpp::utility::cout_logger) - if you wanted to do something more advanced, you can replace this parameter with a lambda just like all other events.
 
 The parameter which we set to false indicates if the function should return once all shards are created. Passing dpp::st_wait here tells the program you do not need to do anything once `bot.start` is called.
 

docpages/install/install-arch-aur.md

@@ -12,9 +12,11 @@ or use your favourite package manager:
 
 ```bash
 # example with `yay` (without root)
-yay -Sy dpp
+yay -Syu dpp
 ```
 
+\note The package is currently outdated. We are looking for a new maintainer. For now, please use `dpp-git` or build it from \ref buildlinux "source".
+
 This will do the following three things:
 
 - Clone the D++ AUR repository to a directory called `dpp`

include/dpp/cluster.h

@@ -1368,11 +1368,9 @@ class DPP_EXPORT cluster {
 	 * @param method Method, e.g. GET, POST
 	 * @param postdata Post data (usually JSON encoded)
 	 * @param callback Function to call when the HTTP call completes. The callback parameter will contain amongst other things, the decoded json.
-	 * @param filename List of filenames to post for POST requests (for uploading files)
-	 * @param filecontent List of file content to post for POST requests (for uploading files)
-	 * @param filemimetypes List of mime types for each file to post for POST requests (for uploading files)
+	 * @param file_data List of files to post for POST requests (for uploading files)
 	 */
-	void post_rest_multipart(const std::string &endpoint, const std::string &major_parameters, const std::string &parameters, http_method method, const std::string &postdata, json_encode_t callback, const std::vector<std::string> &filename = {}, const std::vector<std::string>& filecontent = {}, const std::vector<std::string>& filemimetypes = {});
+	void post_rest_multipart(const std::string &endpoint, const std::string &major_parameters, const std::string &parameters, http_method method, const std::string &postdata, json_encode_t callback, const std::vector<message_file_data> &file_data = {});
 
 	/**
 	 * @brief Make a HTTP(S) request. For use when wanting asynchronous access to HTTP APIs outside of Discord.

include/dpp/discordvoiceclient.h

@@ -564,7 +564,10 @@ class DPP_EXPORT discord_voice_client : public websocket_client
 	snowflake channel_id;
 
 	/**
-	 * @brief The audio type to be sent. The default type is recorded audio.
+	 * @brief The audio type to be sent.
+	 *
+	 * @note On Windows, the default type is overlap audio.
+	 * On all other platforms, it is recorded audio.
 	 *
 	 * If the audio is recorded, the sending of audio packets is throttled.
 	 * Otherwise, if the audio is live, the sending is not throttled.
@@ -594,10 +597,15 @@ class DPP_EXPORT discord_voice_client : public websocket_client
 	 */
 	enum send_audio_type_t
 	{
-	    satype_recorded_audio,
-	    satype_live_audio,
+		satype_recorded_audio,
+		satype_live_audio,
 		satype_overlap_audio
-	} send_audio_type = satype_recorded_audio;
+	} send_audio_type =
+#ifdef _WIN32
+	satype_overlap_audio;
+#else
+	satype_recorded_audio;
+#endif
 
 	/**
 	 * @brief Sets the gain for the specified user.