From 63ddc0f6ba14de9c7a067b553f6b652c5bde1628 Mon Sep 17 00:00:00 2001 From: James Turner Date: Sat, 26 Dec 2020 22:17:33 +0000 Subject: [PATCH] Fix MarkDown syntax --- docs-mini/README-cmake.md | 35 +++++++++++++++++++--------------- docs-mini/README-sentry.md | 39 ++++++++++++++++++++++++-------------- 2 files changed, 45 insertions(+), 29 deletions(-) diff --git a/docs-mini/README-cmake.md b/docs-mini/README-cmake.md index 5a8cc5f47..e08c5f9cf 100644 --- a/docs-mini/README-cmake.md +++ b/docs-mini/README-cmake.md @@ -1,17 +1,17 @@ -= CMake in FlightGear overview = +# CMake in FlightGear overview -CMake has evolved considerably over the years; if you're reading external tutorials on it, ensure -they mention 'modern CMake' since it's very different to the older style. +CMake has evolved considerably in the past decade; if you're reading external tutorials abput it, ensure +they mention 'modern CMake', or the information will be incorrect. -The top-level CMakeList.txt handles configuration options, finding dependencies, and scanning -the rest of the source tree. Across the source tree we add executables, includ the main FGFS -binary but also other helpers and utilities. We also define targets for helper libraries for +The top-level `CMakeLists.txt` handles configuration options, finding dependencies, and scanning +the rest of the source tree. Across the source tree we add executables, including the main FGFS +binary but also other helpers and utilities. We also define targets for helper libraries, for various reasons; for example to build some code with different include paths or flags. -Due to the original code structure, we use some helper functions to collect most of the +Due to the historical code structure, we use some helper functions to collect most of the application sources into two global CMake variables, which are then read and added to the main executable target, in `src/Main/CMakeList.txt`. Therefore, many subdirectories have -a trivial CMakeList.txt which simply calls the helper functions to add its sources: +a trivial `CMakeLists.txt` which simply calls the helper functions to add its sources: ``` include(FlightGearComponent) @@ -29,25 +29,30 @@ set(HEADERS flightgear_component(MyComp "${SOURCES}" "${HEADERS}") ``` -== Configurations == +The global properties used are `FG_SOURCES` and `FG_HEADERS`. -Release builds are built with RelWithDebInfo; this is also the most useful configuration for -development, sicne on Windows, Debug is unusably slow. If trying to optimise performance, +## Configurations + +Official release builds are built with `RelWithDebInfo`; this is also the most useful configuration for +development, since on Windows, `Debug` is unusably slow. If trying to optimise performance, keep in mind that compiler flags must be manually set for `RelWithDebInfo`; they are _not_ automatically inherited from `Release`. +Adding additional configurations is possible: for example for profiling. CMake also picks up +the `CXXFLAGS` environment variable to pass ad-hoc compiler options, without modifying the +build systen. -== Dependencies == +## Dependencies All dependencies should be handled via an `IMPORTED` target: this ensures that include paths, -link options, etc specific to the dependency are handled correclty across different platforms. +link options, etc specific to the dependency are handled correctly across different platforms. -Depending on the dependency, it may supply a Foo-Config.cmake which defines such a target for +For some dependencies, there may be a zFoo-Config.cmakez which defines such a target for you automatically. Or there may be an existing `FindFoo.cmake` which does the same. If neither of these situations exist, create a custom finder file in `CMakeModules`, following the existing examples. -CMake tracks transitive dependencies correctly, so for example if your new dependency is used +CMake tracks transitive dependencies precisely, so for example if your new dependency is used in SimGear, it will automatically be added to the include / link paths for FlightGear based on the SimGear build type. diff --git a/docs-mini/README-sentry.md b/docs-mini/README-sentry.md index 7b5061d88..1b8fbeaa1 100644 --- a/docs-mini/README-sentry.md +++ b/docs-mini/README-sentry.md @@ -1,13 +1,13 @@ -= Sentry.io Cash Reporting = +# Sentry.io Cash Reporting FlightGear can optionally report crashes and serious errors to Sentry.io. We have a sponsored account provided gratis by Sentry; for access to this, ask on the developer list. -== Error conditions == +## Error conditions -If FlightGear crahses, SDentry will automatically submit a report. For non-crash errors, +If FlightGear crahses, Sentry will automatically submit a report. For non-crash errors, we manually submit an exception report. At present this is done whenever we trigger the -'fatalMessageBox', and in other serious situations. Deciding where is appropriate (or not) +`fatalMessageBox`, and in other serious situations. Deciding where is appropriate (or not) to report the error to Sentry is a key challenge of the system, since we don't want to report user misconfiguration problems, but we do want to detect recurring and systematic failures, eg broken aircraft. @@ -17,17 +17,19 @@ better to send errors and filter them on the server side, but this needs to be d with some intelligence; for example we do not (at present) report Nasal runtime errors, since this might overload the system. -== Data Protection == +## Data Protection -We explicitly don't include any personal information in the reports, and disable IP address -collection. Since this makes it hard to cluster reports by user, we instead generate a UUID +We explicitly do not include any personal information in the reports, and disable IP address +collection. This avoids any GPDR obligations for us. +Since this makes it hard to cluster reports by user, we instead generate a UUID corresponding to a FlightGear installation. This gives us a way to anonymously cluster reports -by user, without any personal data disclosure. +by computer, without any personal data disclosure. (So we can determine if a hundred reports of a +crash come from fifty discrete users, or just one) -== Supplementatal Data == +## Supplementatal Data We record various pieces of configuration state as 'tags': such as the OS, graphics card, -key settings (eg, is multi-player enabled, which aircraft is being flown) as _tags_ in +major settings (eg, is multi-player enabled, which aircraft is being flown) as _tags_ in Sentry terminology. This allows grouping of reports by similar tags; for example we can identify that a particular crash only occurs with Intel Graphics, or when flying the C172. @@ -37,16 +39,25 @@ is sent, and give an idea of the path of the user through the application, prior crash. We have breadcrumbs for key events such as the splash-screen completing, the user changing position, or scenery being reloaded. -WARN and ALERT level `SG_LOG` messages are currently included as breadcrumbs automatically; -this means it's important not casually add messages at the levels for non-serious conditions. +`WARN` and `ALERT` level `SG_LOG` messages are currently included as breadcrumbs automatically; +this means it's important not to casually add messages at the levels for non-serious conditions. The integration code has a list of commonly ocurring but non-useful messages which are -skipped from sending; especially some OSG ones related to minor PNG and AC3D data issues. +skipped from sending; especially some OSG ones related to PNG and AC3D data issues. Adding new tags or breadcrumbs should be done with care, but is generally useful, and suggestions in this area are appreciated. -== API == +## API All the API is contained in `sentryIntegration.hxx`, inside the `flightgear` namespace. The methods are no-ops if the Sentry SDK was not available at CMake time, and are also no-ops if the user has disabled sentry reporting. + +## Building + +The API requires the injection of a private API key to report to our account; this +must be kept private of course, so it's injected into official builds at CMake time +on Jenkins, via the environment variable `FLIGHTGEAR_SENTRY_API_KEY`. + +The build must be configured to produce debug symbols, which are uploaded to Sentry +via the `sentry-cli` tool as part of our build scripts. \ No newline at end of file