fly/flightgear
1
0
Fork 0
Code Activity

Fix MarkDown syntax

Browse source
This commit is contained in:
James Turner 2020-12-26 22:17:33 +00:00
parent 7b87b061da
commit 63ddc0f6ba
2 changed files with 45 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
docs-mini/README-cmake.md
View file

@ -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.

39
docs-mini/README-sentry.md
View file

@ -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.