docs: cleanup/polish Markdown files (#5038)

Fixed some language stuff.
    Added alternative to httpbin.
    Updated expected space requirement on Windows.
    Removed unused VS component on Windows.
    Moved Qt Creator formatting to Windows docs.
    Updated nativs link to Qt 6.
    Added missing language to code blocks.
    Removed # Description from PR template and added instructions to fix a GitHub issue.

Co-authored-by: Wissididom <30803034+Wissididom@users.noreply.github.com>
Co-authored-by: pajlada <rasmus.karlsson+github@pajlada.com>
This commit is contained in:
nerix 2023-12-23 11:39:53 +01:00 committed by GitHub
parent d105a68dba
commit 2cb965d352
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
13 changed files with 105 additions and 96 deletions

View file

@ -36,7 +36,7 @@ NOTE: The AppImage from Ubuntu 22.04 is broken. Approach with caution
#### Testing
1. Build a docker image builds the chatterino tests
1. Build a docker image builds the Chatterino tests
`docker buildx build -t chatterino-ubuntu-22.04-test -f .docker/Dockerfile-ubuntu-22.04-test .`
1. Run the tests
`docker run --rm --network=host chatterino-ubuntu-22.04-test`

View file

@ -1,3 +1,5 @@
# Description
<!-- If applicable, please include a summary of what you've changed and what issue is fixed. In the case of a bug fix, please include steps to reproduce the bug so the pull request can be tested -->
<!--
Please include a summary of what you've changed and what issue is fixed.
In the case of a bug fix, please include steps to reproduce the bug so the pull request can be tested.
If this PR fixes an issue on GitHub, mention this here to automatically close it: "Fixes #1234.".
-->

View file

@ -6,13 +6,13 @@ Note on Qt version compatibility: If you are installing Qt from a package manage
### Ubuntu 20.04
_Most likely works the same for other Debian-like distros_
_Most likely works the same for other Debian-like distros._
Install all of the dependencies using `sudo apt install qttools5-dev qt5-image-formats-plugins libqt5svg5-dev libboost-dev libssl-dev libboost-system-dev libboost-filesystem-dev cmake g++ libsecret-1-dev`
Install all the dependencies using `sudo apt install qttools5-dev qt5-image-formats-plugins libqt5svg5-dev libboost-dev libssl-dev libboost-system-dev libboost-filesystem-dev cmake g++ libsecret-1-dev`
### Arch Linux
Install all of the dependencies using `sudo pacman -S --needed qt5-base qt5-imageformats qt5-svg qt5-tools boost rapidjson pkgconf openssl cmake`
Install all the dependencies using `sudo pacman -S --needed qt5-base qt5-imageformats qt5-svg qt5-tools boost rapidjson pkgconf openssl cmake`
Alternatively you can use the [chatterino2-git](https://aur.archlinux.org/packages/chatterino2-git/) package to build and install Chatterino for you.
@ -20,11 +20,11 @@ Alternatively you can use the [chatterino2-git](https://aur.archlinux.org/packag
_Most likely works the same for other Red Hat-like distros. Substitute `dnf` with `yum`._
Install all of the dependencies using `sudo dnf install qt5-qtbase-devel qt5-qtimageformats qt5-qtsvg-devel qt5-linguist libsecret-devel openssl-devel boost-devel cmake`
Install all the dependencies using `sudo dnf install qt5-qtbase-devel qt5-qtimageformats qt5-qtsvg-devel qt5-linguist libsecret-devel openssl-devel boost-devel cmake`
### NixOS 18.09+
Enter the development environment with all of the dependencies: `nix-shell -p openssl boost qt5.full pkg-config cmake`
Enter the development environment with all the dependencies: `nix-shell -p openssl boost qt5.full pkg-config cmake`
## Compile

View file

@ -20,7 +20,7 @@ Local dev machines for testing are available on Apple Silicon on macOS 13.
1. Go to the project directory where you cloned Chatterino2 & its submodules
1. Create a build directory and go into it:
`mkdir build && cd build`
1. Run cmake:
1. Run CMake:
`cmake -DCMAKE_PREFIX_PATH=/opt/homebrew/opt/qt@5 -DOPENSSL_ROOT_DIR=/opt/homebrew/opt/openssl@1.1 ..`
1. Build:
`make`

View file

@ -1,18 +1,18 @@
# Building on Windows
**Note that installing all of the development prerequisites and libraries will require about 40 GB of free disk space. Please ensure this space is available on your `C:` drive before proceeding.**
**Note that installing all the development prerequisites and libraries will require about 12 GB of free disk space. Please ensure this space is available on your `C:` drive before proceeding.**
This guide assumes you are on a 64-bit system. You might need to manually search out alternate download links should you desire to build Chatterino on a 32-bit system.
## Installing prerequisites
## Prerequisites
### Visual Studio
Download and install [Visual Studio 2022 Community](https://visualstudio.microsoft.com/downloads/). In the installer, select "Desktop development with C++" and "Universal Windows Platform development".
Download and install [Visual Studio 2022 Community](https://visualstudio.microsoft.com/downloads/). In the installer, select "Desktop development with C++".
Notes:
- This installation will take about 21 GB of disk space
- This installation will take about 8 GB of disk space
- You do not need to sign in with a Microsoft account after setup completes. You may simply exit the login dialog.
### Qt
@ -26,7 +26,9 @@ Notes:
- Installing the latest **stable** Qt version is advised for new installations, but if you want to use your existing installation please ensure you are running **Qt 5.12 or later**.
#### When prompted which components to install:
#### Components
When prompted which components to install, do the following:
1. Unfold the tree element that says "Qt"
2. Unfold the top most tree element (latest stable Qt version, e.g. `Qt 6.5.3`)
@ -43,7 +45,7 @@ Once Qt is done installing, make sure you add its bin directory to your `PATH` (
<details>
<summary>How to add Qt to PATH</summary>
1. Type "path" in the Windows start menu and click `Edit the system environment variables`.
2. Click the `Environment Variables...` button bottom right.
3. In the `User variables` (scoped to the current user) or `System variables` (system-wide) section, scroll down until you find `Path` and double click it.
@ -78,7 +80,7 @@ Note: This installation will take about 2.1 GB of disk space.
<details>
<summary>OpenSSL</summary>
### For our websocket library, we need OpenSSL 1.1
For our websocket library, we need OpenSSL 1.1.
1. Download OpenSSL for windows, version `1.1.1s`: **[Download](https://web.archive.org/web/20221101204129/https://slproweb.com/download/Win64OpenSSL-1_1_1s.exe)**
2. When prompted, install OpenSSL to `C:\local\openssl`
@ -120,57 +122,69 @@ Then in a terminal, configure conan to use `NMake Makefiles` as its generator:
Open up your terminal with the Visual Studio environment variables (e.g. `x64 Native Tools Command Prompt for VS 2022`), cd to the cloned chatterino2 directory and run the following commands:
1. `mkdir build`
1. `cd build`
1. `conan install .. -s build_type=Release -c tools.cmake.cmaketoolchain:generator="NMake Makefiles" --build=missing --output-folder=.`
1. `cmake -G"NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake" -DCMAKE_PREFIX_PATH="C:\Qt\6.5.3\msvc2019_64" ..`
1. `nmake`
```cmd
mkdir build
cd build
conan install .. -s build_type=Release -c tools.cmake.cmaketoolchain:generator="NMake Makefiles" --build=missing --output-folder=.
cmake -G"NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake" -DCMAKE_PREFIX_PATH="C:\Qt\6.5.3\msvc2019_64" ..
nmake
```
To build a debug build, you'll also need to add the `-s compiler.runtime_type=Debug` flag to the `conan install` invocation. See [this StackOverflow post](https://stackoverflow.com/questions/59828611/windeployqt-doesnt-deploy-qwindowsd-dll-for-a-debug-application/75607313#75607313)
#### Ensure DLLs are available
#### Deploying Qt libraries
Once Chatterino has finished building, to ensure all .dll's are available you can run this from the build directory:
`windeployqt bin/chatterino.exe --release --no-compiler-runtime --no-translations --no-opengl-sw --dir bin/`
Can't find windeployqt? You forgot to add your Qt bin directory (e.g. `C:\Qt\6.5.3\msvc2019_64\bin`) to your `PATH`
### Run the build in Qt Creator
### Developing in Qt Creator
1. Open the `CMakeLists.txt` file by double-clicking it, or by opening it via Qt Creator.
2. You will be presented with a screen that is titled "Configure Project". In this screen, you should have at least one option present ready to be configured, like this:
![Qt Create Configure Project screenshot](https://user-images.githubusercontent.com/69117321/169887645-2ae0871a-fe8a-4eb9-98db-7b996dea3a54.png)
3. Select the profile(s) you want to build with and click "Configure Project".
#### How to run and produce builds
#### Building and running
- In the main screen, click the green "play symbol" on the bottom left to run the project directly.
- Click the hammer on the bottom left to generate a build (does not run the build though).
Build results will be placed in a folder at the same level as the "chatterino2" project folder (e.g. if your sources are at `C:\Users\example\src\chatterino2`, then the build will be placed in an automatically generated folder under `C:\Users\example\src`, e.g. `C:\Users\example\src\build-chatterino-Desktop_Qt_6.5.3_MSVC2019_64bit-Release`.)
- Note that if you are building chatterino purely for usage, not for development, it is recommended that you click the "PC" icon above the play icon and select "Release" instead of "Debug".
- Note that if you are building Chatterino purely for usage, not for development, it is recommended that you click the "PC" icon above the play icon and select "Release" instead of "Debug".
- Output and error messages produced by the compiler can be seen under the "4 Compile Output" tab in Qt Creator.
#### Producing standalone builds
If you build chatterino, the result directories will contain a `chatterino.exe` file in the `$OUTPUTDIR\release\` directory. This `.exe` file will not directly run on any given target system, because it will be lacking various Qt runtimes.
If you build Chatterino, the result directories will contain a `chatterino.exe` file in the `$OUTPUTDIR\release\` directory. This `.exe` file will not directly run on any given target system, because it will be lacking various Qt runtimes.
To produce a standalone package, you need to generate all required files using the tool `windeployqt`. This tool can be found in the `bin` directory of your Qt installation, e.g. at `C:\Qt\6.5.3\msvc2019_64\bin\windeployqt.exe`.
To produce all supplement files for a standalone build, follow these steps (adjust paths as required):
1. Navigate to your build output directory with Windows Explorer, e.g. `C:\Users\example\src\build-chatterino-Desktop_Qt_6.5.3_MSVC2019_64bit-Release`
2. Enter the `release` directory
3. Delete all files except the `chatterino.exe` file. You should be left with a directory only containing `chatterino.exe`.
4. Open a command prompt and execute:
1. Navigate to your build output directory with Windows Explorer, e.g. `C:\Users\example\src\build-chatterino-Desktop_Qt_6.5.3_MSVC2019_64bit-Release`
2. Enter the `release` directory
3. Delete all files except the `chatterino.exe` file. You should be left with a directory only containing `chatterino.exe`.
4. Open a command prompt and execute:
```cmd
cd C:\Users\example\src\build-chatterino-Desktop_Qt_6.5.3_MSVC2019_64bit-Release\release
windeployqt bin/chatterino.exe --release --no-compiler-runtime --no-translations --no-opengl-sw --dir bin/
```
5. The `releases` directory will now be populated with all the required files to make the Chatterino build standalone.
cd C:\Users\example\src\build-chatterino-Desktop_Qt_6.5.3_MSVC2019_64bit-Release\release
C:\Qt\6.5.3\msvc2019_64\bin\windeployqt.exe chatterino.exe
You can now create a zip archive of all the contents in `releases` and distribute the program as is, without requiring any development tools to be present on the target system. (However, the CRT must be present, as usual - see the [README](README.md)).
5. The `releases` directory will now be populated with all the required files to make the chatterino build standalone.
#### Formatting
You can now create a zip archive of all the contents in `releases` and distribute the program as is, without requiring any development tools to be present on the target system. (However, the vcredist package must be present, as usual - see the [README](README.md)).
To automatically format your code, do the following:
1. Download [LLVM 16.0.6](https://github.com/llvm/llvm-project/releases/download/llvmorg-16.0.6/LLVM-16.0.6-win64.exe)
2. During the installation, make sure to add it to your path
3. In Qt Creator, Select `Tools` > `Options` > `Beautifier`
4. Under `General` select `Tool: ClangFormat` and enable `Automatic Formatting on File Save`
5. Under `Clang Format` select `Use predefined style: File` and `Fallback style: None`
### Building on MSVC with AddressSanitizer
@ -183,7 +197,7 @@ copy the file found in `<VisualStudio-installation-path>\VC\Tools\MSVC\<version>
To learn more about AddressSanitizer and MSVC, visit the [Microsoft Docs](https://learn.microsoft.com/en-us/cpp/sanitizers/asan).
### Building/Running in CLion
### Developing in CLion
_Note:_ We're using `build` instead of the CLion default `cmake-build-debug` folder.
@ -196,7 +210,7 @@ Clone the repository as described in the readme. Open a terminal in the cloned f
Now open the project in CLion. You will be greeted with the _Open Project Wizard_. Set the _CMake Options_ to
```
```text
-DCMAKE_PREFIX_PATH=C:\Qt\6.5.3\msvc2019_64\lib\cmake\Qt6
-DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake"
```
@ -227,9 +241,9 @@ Select the `CMake Applications > chatterino` configuration and add a new _Run Ex
</details>
<details>
<summary>Screenshot of chatterino configuration</summary>
<summary>Screenshot of Chatterino configuration</summary>
![Screenshot of chatterino configuration](https://user-images.githubusercontent.com/41973452/160240843-dc0c603c-227f-4f56-98ca-57f03989dfb4.png)
![Screenshot of Chatterino configuration](https://user-images.githubusercontent.com/41973452/160240843-dc0c603c-227f-4f56-98ca-57f03989dfb4.png)
</details>
@ -240,26 +254,24 @@ write `portable` into it.
#### Debugging
To visualize QT types like `QString`, you need to inform CLion and LLDB
To visualize Qt types like `QString`, you need to inform CLion and LLDB
about these types.
1. Set `Enable NatVis renderers for LLDB option`
in `Settings | Build, Execution, Deployment | Debugger | Data Views | C/C++` (should be enabled by default).
2. Use the official NatVis file for QT from [`qt-labs/vstools`](https://github.com/qt-labs/vstools) by saving them to
2. Use the official NatVis file for Qt from [`qt-labs/vstools`](https://github.com/qt-labs/vstools) by saving them to
the project root using PowerShell:
<!--
When switching to QT6 these need to be updated to qt6.natvis.xml.
We need to do the replacement as the QT tools:
https://github.com/qt-labs/vstools/blob/0769d945f8d0040917d654d9731e6b65951e102c/QtVsTools.Package/QtVsToolsPackage.cs#L390-L393
We can't use Invoke-RestMethod here, because it will automatically convert the body to an xml document.
-->
```powershell
(irm "https://github.com/qt-labs/vstools/raw/dev/QtVsTools.Package/qt5.natvis.xml").Replace('##NAMESPACE##::', '') | Out-File qt5.natvis
(iwr "https://github.com/qt-labs/vstools/raw/dev/QtVsTools.Package/qt6.natvis.xml").Content.Replace('##NAMESPACE##::', '') | Out-File qt6.natvis
# [OR] using the permalink
(irm "https://github.com/qt-labs/vstools/raw/0769d945f8d0040917d654d9731e6b65951e102c/QtVsTools.Package/qt5.natvis.xml").Replace('##NAMESPACE##::', '') | Out-File qt5.natvis
(iwr "https://github.com/qt-labs/vstools/raw/1c8ba533bd88d935be3724667e0087fd0796102c/QtVsTools.Package/qt6.natvis.xml").Content.Replace('##NAMESPACE##::', '') | Out-File qt6.natvis
```
Now you can debug the application and see QT types rendered correctly.
Now you can debug the application and see Qt types rendered correctly.
If this didn't work for you, try following
the [tutorial from JetBrains](https://www.jetbrains.com/help/clion/qt-tutorial.html#debug-renderers).

View file

@ -8,12 +8,16 @@ This will require more than 30GB of free space on your hard drive.
1. Install [CMake](https://cmake.org/)
1. Install [git](https://git-scm.com/)
1. Install [vcpkg](https://vcpkg.io/)
- `git clone https://github.com/Microsoft/vcpkg.git`
- `cd .\vcpkg\`
- `.\bootstrap-vcpkg.bat`
- `.\vcpkg integrate install`
- `.\vcpkg integrate powershell`
- `cd ..`
```shell
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg integrate install
.\vcpkg integrate powershell
cd ..
```
1. Configure the environment variables for vcpkg.
Check [this document](https://gist.github.com/mitchmindtree/92c8e37fa80c8dddee5b94fc88d1288b#setting-an-environment-variable-on-windows) for more information for how to set environment variables on Windows.
- Ensure your dependencies are built as 64-bit
@ -31,15 +35,19 @@ This will require more than 30GB of free space on your hard drive.
## Building
1. Clone
- `git clone --recurse-submodules https://github.com/Chatterino/chatterino2.git`
```shell
git clone --recurse-submodules https://github.com/Chatterino/chatterino2.git
```
1. Install dependencies
- `cd .\chatterino2\`
- `vcpkg install`
```powershell
cd .\chatterino2\
vcpkg install
```
1. Build
- `mkdir .\build\`
- `cd .\build\`
- (cmd) `cmake .. -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake`
- (ps1) `cmake .. -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"`
- `cmake --build . --parallel <threads> --config Release`
1. Run
- `.\bin\chatterino2.exe`
```powershell
cmake -B build -DCMAKE_TOOLCHAIN_FILE="$Env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
cd build
cmake --build . --parallel <threads> --config Release
```
When using CMD, use `-DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake` to specify the toolchain.
1. Run `.\bin\chatterino2.exe`

View file

@ -35,7 +35,7 @@ int compare(const QString &a, const QString &b);
```cpp
/*
* Matches a link and returns boost::none if it failed and a
* Matches a link and returns std::nullopt if it failed and a
* QRegularExpressionMatch on success.
* ^^^ This comment just repeats the function signature!!!
*

View file

@ -22,34 +22,29 @@ If you still receive an error about `MSVCR120.dll missing`, then you should inst
To get source code with required submodules run:
```
```shell
git clone --recurse-submodules https://github.com/Chatterino/chatterino2.git
```
or
```
```shell
git clone https://github.com/Chatterino/chatterino2.git
cd chatterino2
git submodule update --init --recursive
```
[Building on Windows](../master/BUILDING_ON_WINDOWS.md)
[Building on Windows with vcpkg](../master/BUILDING_ON_WINDOWS_WITH_VCPKG.md)
[Building on Linux](../master/BUILDING_ON_LINUX.md)
[Building on Mac](../master/BUILDING_ON_MAC.md)
[Building on FreeBSD](../master/BUILDING_ON_FREEBSD.md)
- [Building on Windows](../master/BUILDING_ON_WINDOWS.md)
- [Building on Windows with vcpkg](../master/BUILDING_ON_WINDOWS_WITH_VCPKG.md)
- [Building on Linux](../master/BUILDING_ON_LINUX.md)
- [Building on macOS](../master/BUILDING_ON_MAC.md)
- [Building on FreeBSD](../master/BUILDING_ON_FREEBSD.md)
## Git blame
This project has big commits in the history which for example update all line
endings. To improve the output of git-blame, consider setting:
This project has big commits in the history which touch most files while only doing stylistic changes. To improve the output of git-blame, consider setting:
```
```shell
git config blame.ignoreRevsFile .git-blame-ignore-revs
```
@ -58,19 +53,9 @@ file](./.git-blame-ignore-revs). GitHub does this by default.
## Code style
The code is formatted using clang format in Qt Creator. [.clang-format](src/.clang-format) contains the style file for clang format.
The code is formatted using [clang-format](https://clang.llvm.org/docs/ClangFormat.html). Our configuration is found in the [.clang-format](.clang-format) file in the repository root directory.
### Get it automated with QT Creator + Beautifier + Clang Format
1. Download LLVM: https://github.com/llvm/llvm-project/releases/download/llvmorg-16.0.6/LLVM-16.0.6-win64.exe
2. During the installation, make sure to add it to your path
3. In QT Creator, select `Help` > `About Plugins` > `C++` > `Beautifier` to enable the plugin
4. Restart QT Creator
5. Select `Tools` > `Options` > `Beautifier`
6. Under `General` select `Tool: ClangFormat` and enable `Automatic Formatting on File Save`
7. Under `Clang Format` select `Use predefined style: File` and `Fallback style: None`
Qt creator should now format the documents when saving it.
For more contribution guidelines, take a look at [the wiki](https://wiki.chatterino.com/Contributing%20for%20Developers/).
## Doxygen

View file

@ -5,7 +5,7 @@
- [ ] Updated version code in `src/common/Version.hpp`
- [ ] Updated version code in `CMakeLists.txt`
This can only be "whole versions", so if you're releasing `2.4.0-beta` you'll need to condense it to `2.4.0`
- [ ] Add a new release at the top of of the `releases` key in `resources/com.chatterino.chatterino.appdata.xml`
- [ ] Add a new release at the top of the `releases` key in `resources/com.chatterino.chatterino.appdata.xml`
This cannot use dash to denote a pre-release identifier, you have to use a tilde instead.
- [ ] Updated version code in `.CI/chatterino-installer.iss`

View file

@ -1,6 +1,6 @@
# Test and Benchmark
Chatterino includes a set of unit tests and benchmarks. These can be built using cmake by adding the `-DBUILD_TESTS=On` and `-DBUILD_BENCHMARKS=On` flags respectively.
Chatterino includes a set of unit tests and benchmarks. These can be built using CMake by adding the `-DBUILD_TESTS=On` and `-DBUILD_BENCHMARKS=On` flags respectively.
## Adding your own test

View file

@ -45,7 +45,7 @@ An example plugin is available at [https://github.com/Mm2PL/Chatterino-test-plug
If you prefer, you may use [TypescriptToLua](https://typescripttolua.github.io)
to typecheck your plugins. There is a `chatterino.d.ts` file describing the API
in this directory. However this has several drawbacks like harder debugging at
in this directory. However, this has several drawbacks like harder debugging at
runtime.
## API
@ -161,7 +161,7 @@ See [official documentation](https://www.lua.org/manual/5.4/manual.html#pdf-load
#### `require(modname)`
This is Lua's [`require()`](https://www.lua.org/manual/5.3/manual.html#pdf-require) function.
However the searcher and load configuration is notably different than default:
However, the searcher and load configuration is notably different from the default:
- Lua's built-in dynamic library searcher is removed,
- `package.path` is not used, in its place are two searchers,

View file

@ -1,3 +1,3 @@
Third party libraries are stored here
Third party libraries are stored here.
Fetched via `git submodule update --init --recursive`

View file

@ -1,4 +1,4 @@
To run tests all tests you will need to run the `kennethreitz/httpbin` and `ghcr.io/chatterino/twitch-pubsub-server-test:latest` docker images
To run all tests you will need to run the `kennethreitz/httpbin` and `ghcr.io/chatterino/twitch-pubsub-server-test:latest` docker images.
For example:
@ -6,3 +6,5 @@ For example:
docker run --network=host --detach ghcr.io/chatterino/twitch-pubsub-server-test:latest
docker run -p 9051:80 --detach kennethreitz/httpbin
```
If you're unable to use docker, you can use [httpbox](github.com/kevinastone/httpbox) (`httpbox --port 9051`) and [Chatterino/twitch-pubsub-server-test](https://github.com/Chatterino/twitch-pubsub-server-test/releases/latest) manually.