Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
60 lines (38 loc) · 2.67 KB

CONTRIBUTING.md

File metadata and controls

60 lines (38 loc) · 2.67 KB

Contributors Guide

Requirements

  • a C++20 compiler, such as Visual Studio 2022 or a recent Clang version
  • CMake
  • git

Note for Windows developers

While in general this is a terrible idea, for this project, you may want to run your IDE/debugger elevated, as the program requires elevation.

This is because the API layer community in general has decided to install their layers into HKEY_LOCAL_MACHINE, rather than HKEY_CURRENT_USER, which requires elevation to write to. Individual API layers can't really migrate to HKCU, because layer order is only defined (ish) within one registry hive, and layer ordering matters.

Building

  1. Clone the repository
  2. git submodule update --init (needed once)
  3. Open with Visual Studio Code and use the CMake extensions, or configure and build with separate cmake command

You may want to set the ENABLE_ASAN CMake option to enable Address Sanitizer, which will automatically detect many common memory errors at runtime.

See the GitHub Actions configuration for a full example.

General Guidelines

  • clang-format should be used ('format document' in Visual Studio Code will automatically do this)
  • OS-specific functions should be avoided if possible
  • Where unavoidable, they must be isolated to *_windows* files (e.g. src/APILayers_windows.cpp) or in a windows subfolder (e.g. src/linters/windows/ProgramFilesLinter.cpp).

Adding Additional Warnings

"Warnings" in the UI are instances of LintError, which are generated by a Linter. A LintError can be a FixableLintError, which has a Fix() method.

  • LintError can be instantiated directly
  • FixableLintError must be extended
  • OrderingLintError is a final subclass of FixableLintError for moving a layer to above or below another layer
  • InvalidLayerLintError is a final subclass of FixableLintError that removes completely undesirable layers, such as registry keys referring to missing files.

Layer Ordering Warnings

Additional ordering checks can be added by describing the layer in LayerRules.cpp; the fields are documented in LayerRules.hpp.

Other Warnings

Add a new Linter subclass (using existing linters as an example), and additional subclasses of LintError or FixableLintError if needed. If your new error is not automatically fixable, you probably just want to use LintError.

Layer implementation files contain a single static instance of the linter, e.g.:

class OrderingLinter final : public Linter {
  // ...
};

static OrderingLinter gInstance;

The static instance is needed as the constructor registers the new linter with the linter system.