Skip to content

Latest commit

 

History

History
226 lines (157 loc) · 9.09 KB

CONTRIBUTING.md

File metadata and controls

226 lines (157 loc) · 9.09 KB
Raw

Contributing to the DemoFramework

Table Of Contents

How Can I Contribute

Pull Requests

Preparing the code for a pull request

Beware "FslBuildCheck --tidy" will most likely not run for yocto builds, it might work for those SDK's that use clang.

  1. Ensure you checked in your change locally so you can revert the format changes if need be.

  2. Run FslBuildCheck to do a final format of the code.

    FslBuildCheck.py --format --scan --repair

  3. Check in the changes locally when you are ok with them.

  4. Time to tidy the code, this is the more invasive part that updates the code.

    FslBuildCheck.py --format --scan --tidy --repair

  5. Keep repeating step 4 until the 'tidy' doesn't fix any more issues.

  6. If there were issued reported that couldn't be fixed automatically then fix them manually.

  7. Keep running the checks at step 4 until all issues have been fixed.

  8. The code itself is now ready to do a pull request.

Check resource licenses

All graphical resources like images, textures, fonts and meshes need to have a license attached. We utilize a custom License.json file that covers all resources in the same directory, so if you need to have multiple licenses then you need to put them in separate directories.

The FslBuildCheck.py --license tool can be run in your 'app' directory to scan for common graphical resource files:

FslBuildCheck.py --license --licenseList

Fix all resource license issues.

Create the appropriate meta data

If you are submitting a new demo app you also need to:

  1. Create a Example.jpg screenshot

    FslBuildRun.py -- --Window [0,0,1920,1080] --ScreenshotNamePrefix Example --ScreenshotNameScheme exact --ScreenshotFormat jpg --ScreenshotFrequency 5 --ExitAfterFrame 5 --ForceUpdateTime 16666

    If your app is a console app or the API doesn't support taking screenshots please prepare a relevant screenshot (Example.jpg 1920x1080). Beware for most platforms the screenshot is saved at the "executables current working directory".

    For windows we have a helper batch script that will write the screenshot to the package directory:

    FslBuild.py --ForAllExe "WinScreenshot.bat (EXE) (PACKAGE_PATH)"

  2. Write a description in the README.md

  3. Attach the the argument list to the README.md using this command (WARNING: you might want to check-in your README.md before doing this)

    FslBuildDoc.py --ExtractArguments .

  4. Verify that the app README.md file looks fine using a github markdown viewer (for example visual studio code).

  5. Verify that the root README.md file contains a nice entry for the app.

Styleguides

C++ Styleguide

All C++ code must adhere to format defined by the included .clang-format. For now we utilize the layout provided by clang-format 10.0. It's recommended to utilize a editor that is clang format compatible. Like Visual Studio, Visual Studio Code, Emacs, Vim and lots of others. For more information about clang format check the official documentation.

To further ensure a common style is used in the code we also employ clang-tidy using our .clang-tidy file. For more information about clang tidy check the official documentation.

Manual style recommendations

Before applying all these recommendations manually make sure you take advantage of the automation available using ClangTidy as described here.

  • If possible make sure you sample works on Windows and Yocto, testing on all platforms gives bonus points :)
  • Avoid platform dependent code when possible.
  • All code must have a license attached.
  • Use C++20
    • Use RAII
    • Use "enum class" for enums
    • Use 'nullptr' instead of NULL.
    • Make sure you use the C++ header files and not the C ones (the C headers end in .h the C++ ones do not)
    • Use the C++ or 'API' data types that are available on all platforms, like uint32_t and similar.
    • Use std::size_t not size_t.
    • Use exceptions for error handling.
      • On modern compilers exceptions are cheaper than error code checking (until the exception occurs).
  • Don't use these C++20 features:
  • Don't use 'using namespace' in a header file!
  • Don't use global variables use members instead!
  • Don't go overboard with template code.
  • Never call exit, throw a exception instead.
  • use the FSLLOG3 macros for logging, never printf or std::cout.
  • As a rule of thumb dont use 'fopen' use the ContentManager or PersistentDataManager instead.
  • Keep your functions small. As a rule of thumb keep them under 50 lines.

Memory Handling

  • Don't use malloc or C style memory handling. Use new and utilize the STL classes as appropriate.
  • Use the RAII smarts pointers
  • For dynamically allocated arrays use std::vector instead of managing the memory yourself.

API specific

  • If you just want to exit on a API error code then use the API checking macros instead of doing your own error checking as they will log more detailed information and throw an appropriate exception.
    • EGL_CHECK, GL_CHECK, RAPIDOPENCL_CHECK, RAPIDOPENVX_CHECK, RAPIDVULKAN_CHECK, etc
  • Use the Helper classes as much as possible as they will do the necessary parameter validation and error checking.
    • If your sample is showcasing a specific API call sequence then you might consider not using the helper classes for that sequence.

FslBuildCheck tool-chain examples

WARNING: Before following the below example please ensure you checked in your change locally so you can revert the format changes if need be.

FslBuildCheck --format

The FslBuld tool-chain supports invoking clang-format like this:

FslBuildCheck.py --format --repair

To just preview the proposed changes run it like this:

FslBuildCheck.py --format

Additional arguments can be supplied to clang-format like this

FslBuildCheck.py --format --formatArgs="-h"

FslBuildCheck --tidy

The FslBuld tool-chain supports invoking clang-tidy like this:

FslBuildCheck.py --tidy --repair

To just preview the proposed changes run it like this:

FslBuildCheck.py --tidy

You can run a slightly faster check profile for the initial tidying using

FslBuildCheck.py --tidy --tidyProfile fast --repair

Additional arguments can be supplied directly to clang-tidy like this

FslBuildCheck.py --tidy --tidyArgs="-h"

If you just want to run a specific set of checks you can do it like this:

FslBuildCheck.py --tidy -tidyOverrideChecks clang-analyzer-core.*,bugprone-use-after-move

It's also possible to run both format and tidy at once. This will invoked the tidy first then the format.

FslBuildCheck.py --tidy --format --repair

You can run the check on a specific file like this:

FslBuildCheck.py --format --scan --tidy --repair --file include/FslBase/IO/Path.hpp

You can use Unix shell-style wildcards to run it on a set of files

FslBuildCheck.py --format --scan --tidy --repair  --file *.hpp

Tools

These are just recommended third party tools and plugins, but use them at your own risk!