Developing on the codebase
-----------------------------------
.. note::The `download-and-compile` tool can also work for making code changes, but it is more focused on providing scripted compilation for non-developers

The easiest way to work on the codebase is using the superbuild `CMakeList.txt` checked into `fgmeta`. If you are already familiar with CMake 
superbuilds, you can simply open the `fgmeta` as a workspace in your favourite smart editor (eg, Visual Studio Code), customize `CMakeUserPresets.json` to submit
your local setup, and code, build and debug as normal. The steps below explain this process in more detail.

1. Clone `fgmeta`, then `git submodule init fgdata flightgear simgear`. If you're on Windows, also `git submodule init windows-3rd-party`. We're explicitly 
   listing the submodules here since some submodules don't make sense for most people, and clutter up the build folder. 

2. Update the submodules; this takes some time since initial cloning of `FGData` is slow: `git submodule update --remote`

3. Clone our forked OpenSceneGraph from `https://gitlab.com/flightgear/openscenegraph` (pick a location outside `fgmeta`)

4. Build OpenSceneGraph and install into a suitable local prefix *outside* `fgmeta`; for example specify `~/FGFS/osg-build` as the build directory and `~/FGFS/osg-dist` as the `CMAKE_INSTALL_PREFIX`. (Again
   make sure you don't use the system install prefix of `/usr` for installation, that will cause problems or overwrite your distro OpenSceneGraph)

5. Open the `fgmeta` directory as a workspace in your favourite C++ IDE : VS Code, CLion, etc.

6. Copy `CMakeUserPreset-example.json` to `CMakeUserPresets.json` and modify to suit. Notably, you should set `CMAKE_PREFIX_PATH` to include the prefix you used for OpenSceneGraph. You will 
   probably also need to include the path to your Qt installation, if you want to use the launcher, but this is optional and often not needed for development work.

- on macOS, you are recommended to download the most recent `macos-3rd-party` archive from GitLab, eg from: `https://gitlab.com/flightgear/macos-3rd-party/-/artifacts` : pass the location of
  the extracted files to `CMAKE_PREFIX_PATH` alongside any other paths. This is the easiest way to get the dependencies which are not available via `Homebrew`, such as PLIB and OpenAL-soft.

7. Modern IDEs will detect updates to the CMake presets file and re-run the CMake configuration step, e.g., if you have installed the VS Code CMake integration plugin.

8. Build the code: the super-build will build both SimGear and FlightGear 

Day-to-day development
-------------------------------

- code-indexing should work across both SimGear and FlightGear
- no need to run any installation steps, the super-build handles dependencies correctly, eg if you edit a SimGear file the correct FlightGear pieces will rebuild
- set breakpoints in the code as needed 
- update the `flightgear` and `simgear` modules as needed : note that `fgmeta`'s next branch does *not* receive commits to track the submodules, we assume developers track the HEAD of `next` for
  `simgear` and `flightgear` repositories.
- create e.g., `launch.json` entries as needed (if using VS Code) to facilitate debugging


Invoking CMake manually
----------------------------
If you use an editor that doesn't detect CMake projects automatically, you can manually invoke CMake to create the build, and use `cmake --build` to build. 

For example: `cmake -S fgmeta -B build-fgmeta --preset MyPreset` (assuming you named your preset `MyPreset`, of course)