From 50d7b79f8e7342d2811140487f01ba2c470884ef Mon Sep 17 00:00:00 2001 From: Krystian Ligenza Date: Wed, 6 May 2020 12:21:24 -0400 Subject: [PATCH] MAYA-104031 MAYA-99931 Add Python, CMake guidelines and clang-format configuration --- .clang-format | 28 +++++++++++ .clang-format-exclude | 0 .clang-format-include | 8 +++ doc/codingGuidelines.md | 108 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 144 insertions(+) create mode 100644 .clang-format create mode 100644 .clang-format-exclude create mode 100644 .clang-format-include diff --git a/.clang-format b/.clang-format new file mode 100644 index 0000000000..53d6eb3afb --- /dev/null +++ b/.clang-format @@ -0,0 +1,28 @@ +--- +Language: Cpp + +BasedOnStyle: WebKit +AlignAfterOpenBracket: AlwaysBreak +AlignConsecutiveMacros: 'true' +AlignConsecutiveDeclarations: 'true' +AlignEscapedNewlines: Left +AlignTrailingComments: 'true' +AllowAllConstructorInitializersOnNextLine: 'false' +AllowAllParametersOfDeclarationOnNextLine: 'false' +AllowShortCaseLabelsOnASingleLine: 'true' +AllowShortIfStatementsOnASingleLine: Never +AllowShortLambdasOnASingleLine: All +AllowShortLoopsOnASingleLine: 'true' +AlwaysBreakTemplateDeclarations: MultiLine +BinPackArguments: 'false' +BinPackParameters: 'false' +BreakBeforeTernaryOperators: 'true' +BreakConstructorInitializers: BeforeComma +BreakInheritanceList: BeforeComma +ColumnLimit: '100' +FixNamespaceComments: 'true' +MaxEmptyLinesToKeep: '1' +NamespaceIndentation: None +UseTab: Never + +... diff --git a/.clang-format-exclude b/.clang-format-exclude new file mode 100644 index 0000000000..e69de29bb2 diff --git a/.clang-format-include b/.clang-format-include new file mode 100644 index 0000000000..aad3c80ed2 --- /dev/null +++ b/.clang-format-include @@ -0,0 +1,8 @@ +\.c$ +\.cc$ +\.cpp$ +\.cxx$ +\.h$ +\.hh$ +\.hpp$ +\.hxx$ diff --git a/doc/codingGuidelines.md b/doc/codingGuidelines.md index 63126920af..d2cc0a579f 100644 --- a/doc/codingGuidelines.md +++ b/doc/codingGuidelines.md @@ -227,3 +227,111 @@ Our goal is to develop [maya-usd](https://github.com/autodesk/maya-usd) followin * `nullptr` keyword * … +# Coding guidelines for Python +We are adopting the [PEP-8](https://www.python.org/dev/peps/pep-0008) style for Python Code with the following modification: +* Mixed-case for variable and function names are allowed + +[Pylint](https://www.pylint.org/) is recommended for automation. + + +# Coding guidelines for CMake +## Modern CMake +1. Target Build and Usage requirements should be very clear. +* build requirements ( everything that is needed to build the target ) +* usage requirements ( everything that is needed to use this target as a dependency of another target) +2. Always use target_xxx() and make sure to add the PUBLIC/PRIVATE/INTERFACE keywords as appropriate. +* target_sources +* target_compile_definitions +* target_compile_options +* target_include_directories +* target_link_libraries +* ... + +Keyword meanings: +* **PRIVATE**: requirement should apply to just this target. +* **PUBLIC**: requirement should apply to this target and anything that links to it. +* **INTERFACE**: requirement should apply just to things that link to it. + +3. Don't use Macros that affect all targets (e.g add_definitions, link_libraries, include_directories). +4. Prefer functions over macros whenever reasonable. +5. Treat warnings as errors. +6. Use cmake_parse_arguments as the recommended way for parsing the arguments given to the macro or function. +7. Don't use file(GLOB). +8. Be explicit by calling set_target_properties when it's appropriate. +9. Links against Boost or GTest using imported targets rather than variables: +e.g Boost::filesystem, Boost::system, GTest::GTest + +## Compiler features/flags/definitions +1. Setting or appending compiler flags/definitions via CMAKE_CXX_FLAGS is NOT allowed. +2. Any front-end flags (e.g. -Wno-xxx, cxx_std_xx) should be added to cmake/compiler_config.cmake +3. All current targets, as well as newly added targets, must use mayaUsd_compile_config function in order to get the project-wide flags/definitions. These flags/definitions are added privately via target_compile_features, target_compile_options, target_compile_definitions. Individual targets are still allowed to call target_compile_definitions, target_compile_features individually for any additional flags/definitions by providing appropriate PUBLIC/INTERFACE/PRIVATE keywords. For example: +```cmake +# ----------------------------------------------------------------------------- +# compiler configuration +# ----------------------------------------------------------------------------- +add_library(${UFE_PYTHON_TARGET_NAME} SHARED) +target_compile_definitions(${UFE_PYTHON_TARGET_NAME} + PRIVATE + MFB_PACKAGE_NAME=${UFE_PYTHON_MODULE_NAME} + MFB_ALT_PACKAGE_NAME=${UFE_PYTHON_MODULE_NAME} + MFB_PACKAGE_MODULE="${PROJECT_NAME}.${UFE_PYTHON_MODULE_NAME}" +) +mayaUsd_compile_config(${UFE_PYTHON_TARGET_NAME}) +``` + +## Dynamic linking and Run-time Search Path +Use provided mayaUsd_xxx_rpath() utility functions to handle run-time search path for both MacOSX and Linux. + +## Unit Test +1. Use provided mayaUsd_add_test() function for adding either Gtest or Python tests. +2. Don't add find_package(GTest REQUIRED) in every CMake file with unit tests. Gtest setup is handled automatically for you. +3. For targets that need to link against google test library. Simply add GTest::GTest to target_link_libraries. You don't need to add any Gtest include directory this is done automatically for you. + +## Naming Conventions + 1. CMake commands are case-insensitive. Use lower_case for CMake functions and macros, Use upper_case for CMake variables + ```cmake +# e.g cmake functions +add_subdirectory(schemas) +target_compile_definitions(....) + +# e.g cmake variables +${CMAKE_CXX_COMPILER_ID} +${CMAKE_SYSTEM_NAME} +${CMAKE_INSTALL_PREFIX} +``` + + 2. Use upper_case for Option names +```cmake +# e.g for options names +option(BUILD_USDMAYA_SCHEMAS "Build optional schemas." ON) +option(BUILD_TESTS "Build tests." ON) +option(BUILD_HDMAYA "Build the Maya-To-Hydra plugin and scene delegate." ON) +``` + +3. Use upper_case for Custom variables +```cmake +# e.g for options names +set(QT_VERSION "5.6") + +set(HEADERS + jobArgs.h + modelKindProcessor.h + readJob.h + writeJob.h +) + +set(RESOURCES_INSTALL_PATH ${CMAKE_INSTALL_PREFIX}/lib/usd/${TARGET_NAME}/resources) + +set(USDTRANSACTION_PYTHON_LIBRARY_LOCATION ${AL_INSTALL_PREFIX}/lib/python/AL/usd/transaction) +``` + +4. Respect third-party variables ( don't change them ) +```cmake +# e.g boost +set(BOOST_ROOT ${pxr_usd_location}) +set(Boost_USE_DEBUG_PYTHON ON) +``` + +5. Avoid adding the optional name in endfunction/endmacro([]). +> Although there is no official guideline for Modern CMake practices, the following resources provide ample information on how to adopt these practices: +> [Modern cmake](https://cliutils.gitlab.io/modern-cmake/), [Effective Modern CMake](https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1)