From 35ac9d5f2251b1da5bffd0e43a6047f000617c4e Mon Sep 17 00:00:00 2001 From: pajlada Date: Sat, 4 Mar 2023 12:09:20 +0100 Subject: [PATCH] Update Windows build documentation (#4413) This moves CMake to be our top supported build method, with Qt creator being lower priority now. --- .prettierignore | 3 + BUILDING_ON_WINDOWS.md | 130 ++++++++++++++++-------------- BUILDING_ON_WINDOWS_WITH_VCPKG.md | 30 ++++--- 3 files changed, 93 insertions(+), 70 deletions(-) diff --git a/.prettierignore b/.prettierignore index df4877b88..c23325ed8 100644 --- a/.prettierignore +++ b/.prettierignore @@ -21,3 +21,6 @@ dependencies # vcpkg vcpkg_installed/ + +# Compile commands generated by CMake +compile_commands.json diff --git a/BUILDING_ON_WINDOWS.md b/BUILDING_ON_WINDOWS.md index ef16c1457..11de371d4 100644 --- a/BUILDING_ON_WINDOWS.md +++ b/BUILDING_ON_WINDOWS.md @@ -1,19 +1,50 @@ # Building on Windows -**Note that installing all of the development prerequisites and libraries will require about 30 GB of free disk space. Please ensure this space is available on your `C:` drive before proceeding.** +**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.** 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. -## Visual Studio 2022 +## Installing 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". Notes: -- This installation will take about 17 GB of disk space +- This installation will take about 21 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. -## Boost +### Qt + +1. Visit the [Qt Open Source Page](https://www.qt.io/download-open-source). +2. Scroll down to the bottom +3. Then select "Download the Qt Online Installer" + +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: + +1. Unfold the tree element that says "Qt" +2. Unfold the top most tree element (latest stable Qt version, e.g. `Qt 5.15.2`) +3. Under this version, select the following entries: + - `MSVC 2019 64-bit` (or alternative version if you are using that) + - `Qt WebEngine` (optional) +4. Under the "Tools" tree element (at the bottom), ensure that `Qt Creator X.X.X` and `Debugging Tools for Windows` are selected. (they should be checked by default) +5. Continue through the installer and let the installer finish installing Qt. + +Note: This installation will take about 2 GB of disk space. + +Once Qt is done installing, make sure you add its bin directory to your `PATH` (e.g. `C:\Qt\5.15.2\msvc2019_64\bin`) + +### Advanced dependencies + +These dependencies are only required if you are not using a package manager + +
+Boost 1. First, download a boost installer appropriate for your version of Visual Studio. @@ -29,7 +60,10 @@ Notes: Note: This installation will take about 2.1 GB of disk space. -## OpenSSL +
+ +
+OpenSSL ### For our websocket library, we need OpenSSL 1.1 @@ -37,58 +71,50 @@ Note: This installation will take about 2.1 GB of disk space. 2. When prompted, install OpenSSL to `C:\local\openssl` 3. When prompted, copy the OpenSSL DLLs to "The OpenSSL binaries (/bin) directory". -### For Qt SSL, we need OpenSSL 1.0 - -1. Download OpenSSL for Windows, version `1.0.2u`: **[Download](https://web.archive.org/web/20211109231823/https://slproweb.com/download/Win64OpenSSL-1_0_2u.exe)** -2. When prompted, install it to any arbitrary empty directory. -3. When prompted, copy the OpenSSL DLLs to "The OpenSSL binaries (/bin) directory". -4. Copy the OpenSSL 1.0 files from its `\bin` folder to `C:\local\bin` (You will need to create the folder) -5. Then copy the OpenSSL 1.1 files from its `\bin` folder to `C:\local\bin` (Overwrite any duplicate files) -6. Add `C:\local\bin` to your path folder ([Follow the guide here if you don't know how to do it](https://www.computerhope.com/issues/ch000549.htm#windows10)) - -**If the 1.1.x download link above does not work, try downloading the similar 1.1.x version found [here](https://slproweb.com/products/Win32OpenSSL.html). Note: Don't download the "light" installer, it does not have the required files.** -![Screenshot Slproweb layout](https://user-images.githubusercontent.com/41973452/175827529-97802939-5549-4ab1-95c4-d39f012d06e9.png) - Note: This installation will take about 200 MB of disk space. -## Qt +
-1. Visit the [Qt Open Source Page](https://www.qt.io/download-open-source). -2. Scroll down to the bottom -3. Then select "Download the Qt Online Installer" +## Building -Notes: +### Using CMake -- 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**. +#### Install conan -### When prompted which components to install: +Install [conan](https://conan.io/downloads.html) and make sure it's in your `PATH` (default setting). -1. Unfold the tree element that says "Qt" -2. Unfold the top most tree element (latest stable Qt version, e.g. `Qt 5.15.2`) -3. Under this version, select the following entries: - - `MSVC 2019 64-bit` (or alternative version if you are using that) - - `Qt WebEngine` (optional) -4. Under the "Tools" tree element (at the bottom), ensure that `Qt Creator X.X.X` and `Debugging Tools for Windows` are selected. (they should be checked by default) -5. Continue through the installer and let the installer finish installing Qt. +Then in a terminal, configure conan to use `NMake Makefiles` as its generator: -Note: This installation will take about 2 GB of disk space. +1. Generate a new profile + `conan profile new --detect --force default` +1. Configure the profile to use `NMake Makefiles` as its generator + `conan profile update conf.tools.cmake.cmaketoolchain:generator="NMake Makefiles" default` -## Compile with Breakpad support (Optional) +#### Build -Compiling with Breakpad support enables crash reports that can be of use for developing/beta versions of Chatterino. If you have no interest in reporting crashes anyways, this optional dependency will probably be of no use to you. +Open up your terminal with the Visual Studio environment variables (e.g. `x64 Native Tools Command Prompt for VS 2022`), cd to the cloned c2 directory and run the following commands: -1. Open up `lib/qBreakpad/handler/handler.pro`in Qt Creator -2. Build it in whichever mode you want to build Chatterino in (Debug/Profile/Release) -3. Copy the newly built `qBreakpad.lib` to the following directory: `lib/qBreakpad/build/handler` (You will have to manually create this directory) +1. `mkdir build` +1. `cd build` +1. `conan install .. -s build_type=Release --build=missing` +1. `cmake -G"NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake" -DCMAKE_PREFIX_PATH="C:\Qt\5.15.2\msvc2019_64" ..` +1. `nmake` -## Run the build in Qt Creator +#### Ensure DLLs are available + +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\5.15.2\msvc2019_64\bin`) to your `PATH` + +### Run the build 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 +#### How to run and produce builds - 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). @@ -98,7 +124,7 @@ Build results will be placed in a folder at the same level as the "chatterino2" - 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 +#### 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. @@ -114,27 +140,11 @@ To produce all supplement files for a standalone build, follow these steps (adju cd C:\Users\example\src\build-chatterino-Desktop_Qt_5_15_2_MSVC2019_64bit-Release\release C:\Qt\5.15.2\msvc2019_64\bin\windeployqt.exe chatterino.exe -5. Go to `C:\local\bin\` and copy these dll's into your `release folder`. - - libssl-1_1-x64.dll - libcrypto-1_1-x64.dll - ssleay32.dll - libeay32.dll - -6. The `releases` directory will now be populated with all the required files to make the chatterino build standalone. +5. The `releases` directory will now be populated with all the required files to make the chatterino build standalone. 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)). -## Using CMake - -Open up your terminal with the Visual Studio environment variables, then enter the following commands: - -1. `mkdir build` -2. `cd build` -3. `cmake -G"NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake" ..` -4. `nmake` - -## Building on MSVC with AddressSanitizer +### Building on MSVC with AddressSanitizer Make sure you installed `C++ AddressSanitizer` in your VisualStudio installation like described in the [Microsoft Docs](https://learn.microsoft.com/en-us/cpp/sanitizers/asan#install-the-addresssanitizer). @@ -145,7 +155,7 @@ copy the file found in `\VC\Tools\MSVC\ To learn more about AddressSanitizer and MSVC, visit the [Microsoft Docs](https://learn.microsoft.com/en-us/cpp/sanitizers/asan). -## Building/Running in CLion +### Building/Running in CLion _Note:_ We're using `build` instead of the CLion default `cmake-build-debug` folder. @@ -200,7 +210,7 @@ Now you can run the `chatterino | Debug` configuration. If you want to run the portable version of Chatterino, create a file called `modes` inside of `build/bin` and write `portable` into it. -### Debugging +#### Debugging To visualize QT types like `QString`, you need to inform CLion and LLDB about these types. diff --git a/BUILDING_ON_WINDOWS_WITH_VCPKG.md b/BUILDING_ON_WINDOWS_WITH_VCPKG.md index 4bfac943d..eea127ac3 100644 --- a/BUILDING_ON_WINDOWS_WITH_VCPKG.md +++ b/BUILDING_ON_WINDOWS_WITH_VCPKG.md @@ -1,28 +1,38 @@ # Building on Windows with vcpkg +This will require more than 30GB of free space on your hard drive. + ## Prerequisites -1. Install [Visual Studio](https://visualstudio.microsoft.com/) with "Desktop development with C++" (~9.66 GB) -1. Install [CMake](https://cmake.org/) (~109 MB) -1. Install [git](https://git-scm.com/) (~264 MB) -1. Install [vcpkg](https://vcpkg.io/) (~80 MB) +1. Install [Visual Studio](https://visualstudio.microsoft.com/) with "Desktop development with C++" +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 ..` -1. Configure the environment for vcpkg - - `set VCPKG_DEFAULT_TRIPLET=x64-windows` - - [default](https://github.com/microsoft/vcpkg/blob/master/docs/users/triplets.md#additional-remarks) is `x86-windows` - - `set VCPKG_ROOT=C:\path\to\vcpkg\` - - `set PATH=%PATH%;%VCPKG_ROOT%` +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 + e.g. `setx VCPKG_DEFAULT_TRIPLET x64-windows` + See [documentation about Triplets](https://learn.microsoft.com/en-gb/vcpkg/users/triplets) + [default](https://github.com/microsoft/vcpkg/blob/master/docs/users/triplets.md#additional-remarks) is `x86-windows` + - Set VCPKG_ROOT to the vcpkg path + e.g. `setx VCPKG_ROOT ` + See [VCPKG_ROOT documentation](https://learn.microsoft.com/en-gb/vcpkg/users/config-environment#vcpkg_root) + - Append the vcpkg path to your path + e.g. `setx PATH "%PATH%;"` + - For more configurations, see https://learn.microsoft.com/en-gb/vcpkg/users/config-environment +1. You may need to restart your computer to ensure all your environment variables and what-not are loaded everywhere. ## Building 1. Clone - `git clone --recurse-submodules https://github.com/Chatterino/chatterino2.git` -1. Install dependencies (~21 GB) +1. Install dependencies - `cd .\chatterino2\` - `vcpkg install` 1. Build