diff --git a/docs-mini/README-cmake.md b/docs-mini/README-cmake.md new file mode 100644 index 000000000..5a8cc5f47 --- /dev/null +++ b/docs-mini/README-cmake.md @@ -0,0 +1,59 @@ += 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. + +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 +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 +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: + +``` +include(FlightGearComponent) + +set(SOURCES + foo.cxx + bar.cxx + ) + +set(HEADERS + foo.hxx + bar.hxx + ) + +flightgear_component(MyComp "${SOURCES}" "${HEADERS}") +``` + +== Configurations == + +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, +keep in mind that compiler flags must be manually set for `RelWithDebInfo`; they are _not_ +automatically inherited from `Release`. + + +== 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. + +Depending on the dependency, it may supply a Foo-Config.cmake 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 +in SimGear, it will automatically be added to the include / link paths for FlightGear based on +the SimGear build type. + +If you encounter a case where a downstream target is missing an include path or flag for a +dependency, it typically indicates a bug in your dependency graph. Do _not_ fix it by maanually +modifying the downstream target's include path or flags. Rather, fix your dependency graph +and/or `INTERFACE` exports from your dependency, so that CMake can see the required transitive +dependencies correctly. + diff --git a/docs-mini/README-sentry.md b/docs-mini/README-sentry.md new file mode 100644 index 000000000..7b5061d88 --- /dev/null +++ b/docs-mini/README-sentry.md @@ -0,0 +1,52 @@ += 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 == + +If FlightGear crahses, SDentry 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) +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. + +In general since we have (almost) unlimited event limits on our sponsored plan, it's +better to send errors and filter them on the server side, but this needs to be done +with some intelligence; for example we do not (at present) report Nasal runtime +errors, since this might overload the system. + +== 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 +corresponding to a FlightGear installation. This gives us a way to anonymously cluster reports +by user, without any personal data disclosure. + +== 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 +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. + +Additionally we record 'breadcrumbs'; these are included with an error report if one +is sent, and give an idea of the path of the user through the application, prior to the +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. +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. + +Adding new tags or breadcrumbs should be done with care, but is generally useful, and +suggestions in this area are appreciated. + +== 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.