From 51956e78b38224a6758bedb318ea6df53c3e13fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tor=20Arne=20Vestb=C3=B8?= Date: Fri, 9 Apr 2021 08:54:50 +0200 Subject: [PATCH] feat: Add initial Qt documentation (#3370) --- .../getting-started-config/native.mdx | 2 - .../getting-started-config/native.qt.mdx | 31 ++++++++++++ .../getting-started-install/native.mdx | 9 ++-- .../getting-started-install/native.qt.mdx | 50 +++++++++++++++++++ .../getting-started-primer/native.qt.mdx | 5 ++ src/pages/index.tsx | 1 + src/platforms/native/guides/qt/config.yml | 8 +++ src/wizard/native/index.md | 4 ++ src/wizard/native/qt.md | 47 +++++++++++++++++ 9 files changed, 151 insertions(+), 6 deletions(-) create mode 100644 src/includes/getting-started-config/native.qt.mdx create mode 100644 src/includes/getting-started-install/native.qt.mdx create mode 100644 src/includes/getting-started-primer/native.qt.mdx create mode 100644 src/platforms/native/guides/qt/config.yml create mode 100644 src/wizard/native/qt.md diff --git a/src/includes/getting-started-config/native.mdx b/src/includes/getting-started-config/native.mdx index 063ca538566b8..b28435ccb0477 100644 --- a/src/includes/getting-started-config/native.mdx +++ b/src/includes/getting-started-config/native.mdx @@ -1,5 +1,3 @@ -Import and initialize the Sentry SDK early in your application setup: - ```c #include diff --git a/src/includes/getting-started-config/native.qt.mdx b/src/includes/getting-started-config/native.qt.mdx new file mode 100644 index 0000000000000..9ccb739145a75 --- /dev/null +++ b/src/includes/getting-started-config/native.qt.mdx @@ -0,0 +1,31 @@ +```cpp +#include +#include + +int main(int argc, char *argv[]) +{ + sentry_options_t *options = sentry_options_new(); + sentry_options_set_dsn(options, "___PUBLIC_DSN___"); + sentry_options_set_release(options, "my-project-name@2.3.12"); + sentry_init(options); + + // Make sure everything flushes + auto sentryShutdown = qScopeGuard([] { sentry_shutdown(); }); + + QApplication app(argc, argv); + QWidget widget; + widget.show(); + + return app.exec(); +} +``` + +Alternatively, the DSN can be passed as `SENTRY_DSN` environment variable during runtime. This can be especially useful for server applications. + + + +Calling `sentry_shutdown()` before exiting the application is critical. It +ensures that events can be sent to Sentry before execution stops. Otherwise, +event data may be lost. + + diff --git a/src/includes/getting-started-install/native.mdx b/src/includes/getting-started-install/native.mdx index f79127168ced9..01569640daa6f 100644 --- a/src/includes/getting-started-install/native.mdx +++ b/src/includes/getting-started-install/native.mdx @@ -1,24 +1,25 @@ The Native SDK currently supports **Windows**, **macOS**, **Linux**, and **Android**. -To build the SDK, download the latest release of the SDK from the [Releases page](https://github.com/getsentry/sentry-native/releases). The SDK is managed as a [CMake] project, which additionally supports several configuration options, such as the backend to use. +To build the SDK, download the latest sources from the [Releases page](https://github.com/getsentry/sentry-native/releases). The SDK is managed as a [CMake] project, which additionally supports several configuration options, such as the backend to use. For example, `CMake` can be used like this (on macOS): ```shell # configure the cmake build into the `build` directory, with crashpad (on macOS) -cmake -B build -D SENTRY_BACKEND=crashpad --config RelWithDebInfo +cmake -B build -D SENTRY_BACKEND=crashpad --config RelWithDebInfo -S . # build the project cmake --build build --config RelWithDebInfo --parallel # install the resulting artifacts into a specific prefix cmake --install build --prefix install # which will result in the following (on macOS): -exa --tree install +exa --tree install --level 2 install ├── bin │ └── crashpad_handler ├── include │ └── sentry.h └── lib + ├── cmake ├── libsentry.dylib └── libsentry.dylib.dSYM ``` @@ -27,6 +28,6 @@ install -When using the _Crashpad backend_, which is the default on Windows and macOS, the `crashpad_handler` binary has to be shipped alongside the application binary. See the [Crashpad documentation](configuration/backends/crashpad/) for more information. +When using the _Crashpad backend_, which is the default on Windows and macOS, the `crashpad_handler` binary has to be shipped alongside the application binary. See the [Crashpad documentation](/platforms/native/configuration/backends/crashpad/) for more information. diff --git a/src/includes/getting-started-install/native.qt.mdx b/src/includes/getting-started-install/native.qt.mdx new file mode 100644 index 0000000000000..6e90b75aaea0d --- /dev/null +++ b/src/includes/getting-started-install/native.qt.mdx @@ -0,0 +1,50 @@ +The Qt integration is part of the [`sentry-native`](https://github.com/getsentry/sentry-native/) SDK, +which currently supports Windows, macOS, Linux, and Android. Both Qt 5 and Qt 6 are supported. + +To build the SDK, download the latest sources from the [Releases page](https://github.com/getsentry/sentry-native/releases). The SDK is managed as a [CMake] project, which additionally supports several configuration options, such as the backend to use. + +To enable the Qt integration set the `SENTRY_INTEGRATION_QT` option to `YES`. + + + +If the Qt libraries are not installed in one of the predefined `CMake` [system prefix paths](https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_PREFIX_PATH.html), where they can be found by `CMake`, you will need to set [`CMAKE_PREFIX_PATH`](https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html) explicitly. + + + +For example (on macOS): + +```shell +# Configure the cmake build into the `build` directory, +# with crashpad, and Qt integration (on macOS). +cmake -B build \ + -D SENTRY_BACKEND=crashpad \ + -D SENTRY_INTEGRATION_QT=YES \ + --config RelWithDebInfo \ + -S . + +# Build the project +cmake --build build --config RelWithDebInfo --parallel + +# Install the resulting artifacts into a specific prefix +cmake --install build --prefix install + +# Which will result in the following (on macOS): +exa --tree install --level 2 +install +├── bin +│ └── crashpad_handler +├── include +│ └── sentry.h +└── lib + ├── cmake + ├── libsentry.dylib + └── libsentry.dylib.dSYM +``` + +[cmake]: https://cmake.org/cmake/help/latest/ + + + +When using the _Crashpad backend_, which is the default on Windows and macOS, the `crashpad_handler` binary has to be shipped alongside the application binary. See the [Crashpad documentation](/platforms/native/configuration/backends/crashpad/) for more information. + + diff --git a/src/includes/getting-started-primer/native.qt.mdx b/src/includes/getting-started-primer/native.qt.mdx new file mode 100644 index 0000000000000..48e8f3879fc69 --- /dev/null +++ b/src/includes/getting-started-primer/native.qt.mdx @@ -0,0 +1,5 @@ + + +_Sentry's Qt integration enables automatic reporting of errors, exceptions, and log messages._ + + diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 775230cce4b05..7234e927137e9 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -32,6 +32,7 @@ const HIGHLIGHTED_PLATFORMS = [ "java.spring-boot", "ruby.rails", "flutter", + "native.qt" ]; const IndexPage = () => { diff --git a/src/platforms/native/guides/qt/config.yml b/src/platforms/native/guides/qt/config.yml new file mode 100644 index 0000000000000..140cc2a1b733e --- /dev/null +++ b/src/platforms/native/guides/qt/config.yml @@ -0,0 +1,8 @@ +title: Qt +description: "Learn how to use Sentry with Qt." +categories: + - desktop + - mobile +redirect_from: + - /platforms/qt/ + - /platforms/native/qt/ diff --git a/src/wizard/native/index.md b/src/wizard/native/index.md index e53466ed639e4..46e042585050b 100644 --- a/src/wizard/native/index.md +++ b/src/wizard/native/index.md @@ -38,3 +38,7 @@ sentry_capture_event(sentry_value_new_message_event( /* message */ "It works!" )); ``` + +If you're new to Sentry, use the email alert to access your account and complete a product tour. + +If you're an existing user and have disabled alerts, you won't receive this email. diff --git a/src/wizard/native/qt.md b/src/wizard/native/qt.md new file mode 100644 index 0000000000000..4c0b65f524606 --- /dev/null +++ b/src/wizard/native/qt.md @@ -0,0 +1,47 @@ +--- +name: Qt +doc_link: https://docs.sentry.io/platforms/native/guides/qt/ +support_level: production +type: framework +--- + +Install the SDK by downloading the [latest release](https://github.com/getsentry/sentry-native/releases). Next, follow the +instructions in the [_Native SDK Documentation_](/platforms/native/guides/qt/) to build the SDK library. + +Import and initialize the Sentry SDK early in your application setup: + +```cpp +#include +#include + +int main(int argc, char *argv[]) +{ + sentry_options_t *options = sentry_options_new(); + sentry_options_set_dsn(options, "___PUBLIC_DSN___"); + sentry_init(options); + + // Make sure everything flushes + auto sentryShutdown = qScopeGuard([] { sentry_shutdown(); }); + + QApplication app(argc, argv); + /* ... */ + return app.exec(); +} +``` + +Alternatively, the DSN can be passed as `SENTRY_DSN` environment variable during +runtime. This can be especially useful for server applications. + +The quickest way to verify Sentry in your Qt application is by capturing a message: + +```c +sentry_capture_event(sentry_value_new_message_event( + /* level */ SENTRY_LEVEL_INFO, + /* logger */ "custom", + /* message */ "It works!" +)); +``` + +If you're new to Sentry, use the email alert to access your account and complete a product tour. + +If you're an existing user and have disabled alerts, you won't receive this email.