diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 94f4af81da..92b6ac7e07 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -202,3 +202,9 @@ repos: hooks: - id: conventional-precommit-linter stages: [commit-msg] + - repo: https://github.com/espressif/astyle_py.git + rev: v1.0.2 + hooks: + - id: astyle_py + # If you are modifying astyle version, update tools/format.sh as well + args: ['--astyle-version=3.4.7', '--rules=tools/ci/astyle_rules.yml'] diff --git a/docs/en/contribute/style-guide.rst b/docs/en/contribute/style-guide.rst index d3a5d84bf3..4e48b5d88d 100644 --- a/docs/en/contribute/style-guide.rst +++ b/docs/en/contribute/style-guide.rst @@ -193,15 +193,19 @@ For updating a single commit, it is possible to run ``dos2unix FILENAME`` and th Formatting Your Code ^^^^^^^^^^^^^^^^^^^^ -You can use ``astyle`` program to format your code according to the above recommendations. +ESP-IDF uses Astyle to format source code. The configuration is stored in :project_file:`tools/ci/astyle-rules.yml` file. -If you are writing a file from scratch, or doing a complete rewrite, feel free to re-format the entire file. If you are changing a small portion of file, do not re-format the code you did not change. This will help others when they review your changes. - -To re-format a file, run: +Initially, all components are excluded from formatting checks. You can enable formatting checks for the component by removing it from ``components_not_formatted_temporary`` list. Then run: .. code-block:: bash - tools/format.sh components/my_component/file.c + pre-commit run --files astyle_py + +Alternatively, you can run ``astyle_py`` manually. You can install it with ``pip install astyle_py==VERSION``. Make sure you have the same version installed as the one specified in :project_file:`.pre-commit-config.yaml` file. With ``astyle_py`` installed, run: + +.. code-block:: bash + + astyle_py --rules=$IDF_PATH/tools/ci/astyle-rules.yml Type Definitions diff --git a/tools/ci/astyle-rules.yml b/tools/ci/astyle-rules.yml new file mode 100644 index 0000000000..7fa747ff22 --- /dev/null +++ b/tools/ci/astyle-rules.yml @@ -0,0 +1,184 @@ +DEFAULT: + # These formatting options will be used by default. + # If you are modifying this, update tools/format.sh as well! + options: "--style=otbs --attach-namespaces --attach-classes --indent=spaces=4 --convert-tabs --align-reference=name --keep-one-line-statements --pad-header --pad-oper --unpad-paren --max-continuation-indent=120" + +submodules: + # Don't format the code in submodules + check: false + include: + - "/components/bootloader/subproject/components/micro-ecc/micro-ecc/" + - "/components/bt/controller/lib_esp32/" + - "/components/bt/controller/lib_esp32c2/esp32c2-bt-lib/" + - "/components/bt/controller/lib_esp32c3_family/" + - "/components/bt/controller/lib_esp32c6/esp32c6-bt-lib/" + - "/components/bt/controller/lib_esp32h2/esp32h2-bt-lib/" + - "/components/bt/host/nimble/nimble/" + - "/components/cmock/CMock/" + - "/components/esp_coex/lib/" + - "/components/esp_phy/lib/" + - "/components/esp_wifi/lib/" + - "/components/heap/tlsf/" + - "/components/ieee802154/lib/" + - "/components/json/cJSON/" + - "/components/lwip/lwip/" + - "/components/mbedtls/mbedtls/" + - "/components/mqtt/esp-mqtt/" + - "/components/openthread/lib/" + - "/components/openthread/openthread/" + - "/components/protobuf-c/protobuf-c/" + - "/components/spiffs/spiffs/" + - "/components/unity/unity/" + +components_not_formatted_temporary: + # Formatting in these components isn't checked yet. + # For each of these components, decide whether it should be formatted or not. + # 1. If yes, format the code and remove the component from the exclude list. + # Add special rules for upstream source files, if necessary. + # To reformat the files: + # - Remove the directory from this exclude list + # - Run 'git add .astyle-rules.yml' + # - Run 'pre-commit run --all-files' + # 2. If no, move it to 'components_not_formatted_permanent' section below. + check: false + include: + - "/components/app_trace/" + - "/components/app_update/" + - "/components/bootloader_support/" + - "/components/bootloader/" + - "/components/bt/" + - "/components/cmock/" + - "/components/console/" + - "/components/cxx/" + - "/components/driver/" + - "/components/efuse/" + - "/components/esp_adc/" + - "/components/esp_app_format/" + - "/components/esp_bootloader_format/" + - "/components/esp_coex/" + - "/components/esp_common/" + - "/components/esp_eth/" + - "/components/esp_event/" + - "/components/esp_gdbstub/" + - "/components/esp_hid/" + - "/components/esp_http_client/" + - "/components/esp_http_server/" + - "/components/esp_https_ota/" + - "/components/esp_https_server/" + - "/components/esp_hw_support/" + - "/components/esp_lcd/" + - "/components/esp_local_ctrl/" + - "/components/esp_mm/" + - "/components/esp_netif/" + - "/components/esp_partition/" + - "/components/esp_phy/" + - "/components/esp_pm/" + - "/components/esp_psram/" + - "/components/esp_ringbuf/" + - "/components/esp_rom/" + - "/components/esp_system/" + - "/components/esp_timer/" + - "/components/esp_wifi/" + - "/components/esp-tls/" + - "/components/espcoredump/" + - "/components/esptool_py/" + - "/components/fatfs/" + - "/components/freertos/" + - "/components/hal/" + - "/components/heap/" + - "/components/idf_test/" + - "/components/ieee802154/" + - "/components/json/" + - "/components/linux/" + - "/components/log/" + - "/components/lwip/" + - "/components/mbedtls/" + - "/components/mqtt/" + - "/components/newlib/" + - "/components/nvs_flash/" + - "/components/nvs_sec_provider/" + - "/components/openthread/" + - "/components/partition_table/" + - "/components/perfmon/" + - "/components/protobuf-c/" + - "/components/protocomm/" + - "/components/pthread/" + - "/components/riscv/" + - "/components/sdmmc/" + - "/components/soc/" + - "/components/spi_flash/" + - "/components/spiffs/" + - "/components/tcp_transport/" + - "/components/touch_element/" + - "/components/ulp/" + - "/components/unity/" + - "/components/usb/" + - "/components/vfs/" + - "/components/wear_levelling/" + - "/components/wifi_provisioning/" + - "/components/wpa_supplicant/" + - "/components/xtensa/" + - "/examples/bluetooth/" + - "/examples/build_system/" + - "/examples/common_components/" + - "/examples/custom_bootloader/" + - "/examples/cxx/" + - "/examples/ethernet/" + - "/examples/get-started/" + - "/examples/mesh/" + - "/examples/network/" + - "/examples/openthread/" + - "/examples/peripherals/" + - "/examples/phy/" + - "/examples/protocols/" + - "/examples/provisioning/" + - "/examples/security/" + - "/examples/storage/" + - "/examples/system/" + - "/examples/wifi/" + - "/examples/zigbee/" + - "/tools/esp_app_trace/test/" + - "/tools/mocks/" + - "/tools/test_apps/" + - "/tools/unit-test-app/" + +components_not_formatted_permanent: + # Files which are not supposed to be formatted. + # Typically, these are: + # - Upstream source code we don't want to modify + # - Generated files + check: false + include: + # Xtensa header files (generated) + - "/components/xtensa/esp32/" + - "/components/xtensa/esp32s2/" + - "/components/xtensa/esp32s3/" + - "/components/xtensa/include/xtensa/" + # FAT FS (upstream source code) + - "/components/fatfs/src/" + # Nginx HTTP parser (upstream source code) + - "/components/http_parser/" + # Argtable (upstream source code) + - "/components/console/argtable3/" + # Linenoise (upstream source code) + - "/components/console/linenoise/" + # Catch (upstream source code) + - "/tools/catch/catch.hpp" + # FreeRTOS kernel files (upstream source code). + - "/components/freertos/FreeRTOS-Kernel/" + - "/components/freertos/FreeRTOS-Kernel-SMP/" + - "/components/freertos/FreeRTOS-Kernel-V10.5.1/" + # Segger SystemView (upstream source code). + # Could also try to find suitable astyle options, instead. + - "/components/app_trace/sys_view/Config/" + - "/components/app_trace/sys_view/Sample/" + - "/components/app_trace/sys_view/SEGGER/" + # SoC header files (generated) + - "/components/soc/*/include/soc/" + +docs: + # Docs directory contains some .inc files, which are not C include files + # and should not be formatted + check: false + include: + - "/docs/**/*.inc" diff --git a/tools/ci/exclude_check_tools_files.txt b/tools/ci/exclude_check_tools_files.txt index eac77c20c9..e9521402f2 100644 --- a/tools/ci/exclude_check_tools_files.txt +++ b/tools/ci/exclude_check_tools_files.txt @@ -11,6 +11,7 @@ tools/check_term.py tools/check_python_dependencies.py tools/python_version_checker.py tools/generate_debug_prefix_map.py +tools/ci/astyle-rules.yml tools/ci/checkout_project_ref.py tools/ci/ci_fetch_submodule.py tools/ci/ci_get_mr_info.py @@ -31,7 +32,6 @@ tools/ci/push_to_github.sh tools/ci/python_packages/wifi_tools.py tools/ci/utils.sh tools/eclipse-code-style.xml -tools/format-minimal.sh tools/format.sh tools/mocks/**/* tools/set-submodules-to-github.sh diff --git a/tools/format-minimal.sh b/tools/format-minimal.sh deleted file mode 100644 index 36787d22dd..0000000000 --- a/tools/format-minimal.sh +++ /dev/null @@ -1,9 +0,0 @@ -#!/usr/bin/env bash -# Runs astyle with parameters which should be checked in a pre-commit hook -astyle \ - --style=otbs \ - --indent=spaces=4 \ - --convert-tabs \ - --keep-one-line-statements \ - --pad-header \ - "$@" diff --git a/tools/format.sh b/tools/format.sh index e9b8b2dd3f..62778b3b75 100755 --- a/tools/format.sh +++ b/tools/format.sh @@ -1,14 +1,25 @@ #!/usr/bin/env bash -# Runs astyle with the full set of formatting options -astyle \ +set -euo pipefail + +if [ ! -x "$(command -v astyle_py)" ]; then + echo "astyle_py not found, please install astyle_py:" + echo " pip install -U astyle_py==VERSION" + echo "where VERSION is the same as in .pre-commit-config.yaml." + exit 1 +fi + +# "--astyle-version" here has to be in sync with pre-commit-config.yaml. +# The rest of the options have to be in sync with the default rules in tools/ci/astyle-rules.yml. +astyle_py --astyle-version=3.4.7 \ --style=otbs \ --attach-namespaces \ --attach-classes \ --indent=spaces=4 \ --convert-tabs \ - --align-pointer=name \ --align-reference=name \ --keep-one-line-statements \ --pad-header \ --pad-oper \ + --unpad-paren \ + --max-continuation-indent=120 \ "$@"