From b79581854024dcf84e027dbafa9472ca074b0b44 Mon Sep 17 00:00:00 2001 From: shenleban tongying Date: Thu, 11 Jul 2024 14:45:55 -0400 Subject: [PATCH] doc: exactly how to build GD in local machine (#1675) --- .github/workflows/PR-check-cmake.yml | 5 - website/docs/developer.md | 120 +++++++++++++++++++----- website/docs/howto/build_from_source.md | 4 +- website/mkdocs.yml | 2 +- 4 files changed, 98 insertions(+), 33 deletions(-) diff --git a/.github/workflows/PR-check-cmake.yml b/.github/workflows/PR-check-cmake.yml index 2e3454bc..f4237ae3 100644 --- a/.github/workflows/PR-check-cmake.yml +++ b/.github/workflows/PR-check-cmake.yml @@ -10,11 +10,6 @@ on: - master - experimental - staged - paths-ignore: - - "docs/**" - - "*.md" - - "locale/**" - - "website/**" jobs: job_ubuntu_build_check: name: ubuntu Build and analyze diff --git a/website/docs/developer.md b/website/docs/developer.md index 71267d4f..fc552fd5 100644 --- a/website/docs/developer.md +++ b/website/docs/developer.md @@ -1,34 +1,104 @@ -Developing GoldenDict is not hard. +If you know some C++ and optionally some Qt, you can start to modify GoldenDict right now. -If you know some C++ and optionally some Qt, you can start to modify GoldenDict right now: +This page is a brief introduction on how to get started. -## Install Qt and QtCreator - (On Linux, install dependencies) +For technical details see [how to build from source](howto/build_from_source.md). + +## 1. Install Qt + +To install Qt on macOS or Windows, uses the [Qt Online Installer](https://doc.qt.io/qt-6/get-and-install-qt.html). It can be downloaded from [Qt for Open Source](https://www.qt.io/download-open-source). + +Those Qt components are needed + ++ Qt + + 6.7.2 (Or another version) + + MSVC 2019 (or MSVC 2022) + + Qt5 Compatible Module + + Additional Libraries + + Qt Image formats + + Qt MultiMedia + + Qt Positioning + + Qt SerialPort (? super weird here, but it is needed.) + + Qt Speech + + Qt Webchannel + + Qt Webengine + + Qt Creator (optional) + + CMake + + Ninja + +Note that MinGW is not supported. + +CMake and Ninja are needed. + +## 2. Install a compiler + +For windows, MSVC can be obtained by [installing Visual Studio's "Desktop development with C++"](https://learn.microsoft.com/cpp/build/vscpp-step-0-installation). + +For macOS, install [XCode](https://developer.apple.com/xcode/). + +## 3. Obtain dependencies + +For Windows, prebuilt libraries will be automatically downloaded. + +For macOS, install [Homebrew](https://brew.sh/) and install related packages as described in [how to build from source](howto/build_from_source.md) or search `brew install` command in [macOS release's build file](https://github.com/xiaoyifang/goldendict-ng/blob/staged/.github/workflows/release-macos-homebrew.yml). + +## 4. Build + +First, get GoldenDict's source code by [Cloning a repository](https://docs.github.com/repositories/creating-and-managing-repositories/cloning-a-repository). + +Then choose your favorite IDE/editor and load the `CMakeLists.txt`. If unsure, just use Qt Creator. + +### Qt Creator + +Open `CMakeLists.txt` from Qt Creator, then you wil choose a "Kit" which is pretty much a Qt installation. + +Qt Creator usually can auto detect your Qt installation. In case it doesn't, check out "Kit" settings. Note that, the compiler must be set to MSVC on Windows. + +By default everything will be built, you can disable ffmpeg, epwing... + +![](https://github.com/xiaoyifang/goldendict-ng/assets/20123683/49f6a85e-50ec-4467-b0e4-cf088d218053) + +Then, hit the "Run" button at bottom-right corner should build and run GoldenDict. + +### Command Line only +See [how to build from source](howto/build_from_source.md). + +[Qt's doc: Building projects on the command line](https://doc.qt.io/qt-6/cmake-build-on-cmdline.html) + +### Visual Studio +VS2022 has CMake support. After opening the source code folder, VS will starts to configure CMake but likely won't succeed. + +You need to add Qt's path and other options to "CMake command arguments". Then, "save" the dialog with Ctrl+S or click one of the many "(re)configure cache" buttons. + +![](https://github.com/xiaoyifang/goldendict-ng/assets/20123683/33a52c52-2e8a-4b8c-bb05-4a753f95ff7e) + +Click run will build the project, but the `.exe` would not run, because the dependencies are not copied. + +Simply click "install", which is actually copying dependencies. + +![](https://github.com/xiaoyifang/goldendict-ng/assets/20123683/02e843b1-0842-445c-919c-75618346aaaf) + +### Visual Studio Code + +Install [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools). + +Then open GoldenDict's folder, and the CMake extension will kicks in. + +Then add Qt's path and various other options to configure arguments. - Windows(qtcreator for example) -### Prerequisite -Install visual studio community ,choose C++ component. - -QtCreator Packages: ``` -[x]qtX.X.X version -[x]MSVC2019 /GCC -[x]Qt5 Compatible Module -[*]Additional - [x]Qt Image formats - [x]Qt MultiMedia - [x]Qt Positioning - [x]Qt speech - [x]Qt webchannel - [x]Qt webengine +-DCMAKE_PREFIX_PATH={Your Qt install path}\6.7.2\msvc2019_64 ``` -## Coding Standards +![](https://github.com/xiaoyifang/goldendict-ng/assets/20123683/bd87155e-2e61-41d5-81e2-7bfb1f13c4c4) + +### CLion +### XCode +### CMake GUI +### LSP + Editor? + +## Related Things Please follow [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) and write modern C++ code. -Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org) - -Reformat changes with `clang-format` [how to use clang-format](https://github.com/xiaoyifang/goldendict/blob/staged/howto/how%20to%20use%20.clang-format%20to%20format%20the%20code.md) - -Remember to enable `clang-tidy` support on your editor so that `.clang-tidy` will be respected. +[Qt's documentation](https://doc.qt.io/) diff --git a/website/docs/howto/build_from_source.md b/website/docs/howto/build_from_source.md index ed01348e..24df5838 100644 --- a/website/docs/howto/build_from_source.md +++ b/website/docs/howto/build_from_source.md @@ -1,3 +1,5 @@ +The `release-*` and `PR-check-*` workflow files under `.github` in the source code has actual build & commands for reference. + ## Dependencies * C++17 compiler (For windows it must be MSVC) @@ -46,8 +48,6 @@ cmake --build build_dir cmake --install ./build_dir/ ``` -The `release-*` and `PR-check-*` workflow files under `.github` in the source code has actual build & commands for reference. - ### Feature flags Append `-D{flag_names}=ON/OFF` to cmake's config step. diff --git a/website/mkdocs.yml b/website/mkdocs.yml index 0d6606a5..3f6b6910 100644 --- a/website/mkdocs.yml +++ b/website/mkdocs.yml @@ -51,8 +51,8 @@ nav: - Report Bugs & Feedbacks: feedbacks.md - Development Info: - Start develop: developer.md - - Architecture: architecture.md - Build from source: howto/build_from_source.md + - Architecture: architecture.md - Customize the opencc: howto/how to customize the opencc.md - Use .clang-format: howto/how to use .clang-format to format the code.md - Breadpad crash analysis: howto/how to use breadpad crash analysis.md