From 0cf491bcb503c710cb94d7f695dbd37b55778ff8 Mon Sep 17 00:00:00 2001 From: RedworkDE <10944644+RedworkDE@users.noreply.github.com> Date: Tue, 16 May 2023 18:38:46 +0200 Subject: [PATCH] Allow validating the extension api against a reference version and a list of known changes. --- .github/workflows/linux_builds.yml | 6 + .../4.0-stable.expected | 197 ++++++++++++++++++ misc/scripts/validate_extension_api.sh | 60 ++++++ 3 files changed, 263 insertions(+) create mode 100644 misc/extension_api_validation/4.0-stable.expected create mode 100755 misc/scripts/validate_extension_api.sh diff --git a/.github/workflows/linux_builds.yml b/.github/workflows/linux_builds.yml index dc313359ab8..aa30e5a55e4 100644 --- a/.github/workflows/linux_builds.yml +++ b/.github/workflows/linux_builds.yml @@ -32,6 +32,7 @@ jobs: build-mono: true proj-conv: true artifact: true + compat: true - name: Editor with doubles and GCC sanitizers (target=editor, tests=yes, dev_build=yes, precision=double, use_asan=yes, use_ubsan=yes, linker=gold) cache-name: linux-editor-double-sanitizers @@ -202,6 +203,11 @@ jobs: scons target=template_debug dev_build=yes cd ../.. + - name: Check for GDExtension compatibility + if: ${{ matrix.compat }} + run: | + ./misc/scripts/validate_extension_api.sh "${{ matrix.bin }}" || true # don't fail the CI for now + - name: Prepare artifact if: ${{ matrix.artifact }} run: | diff --git a/misc/extension_api_validation/4.0-stable.expected b/misc/extension_api_validation/4.0-stable.expected new file mode 100644 index 00000000000..ab9e7b0bea5 --- /dev/null +++ b/misc/extension_api_validation/4.0-stable.expected @@ -0,0 +1,197 @@ +This file contains the expected output of --validate-extension-api when run against the extension_api.json of the +4.0-stable tag (the basename of this file). + +Only lines that start with "Validate extension JSON:" matter, everything else is considered a comment and ignored. They +should instead be used to justify these changes and describe how users should work around these changes. + +======================================================================================================================== + +GH-74736 +-------- +Validate extension JSON: Error: Field 'classes/MenuBar/properties/start_index': type changed value in new API, from "bool" to "int". + +The previous type was simply wrong and the getter and setter already used int. + + +GH-74671 +-------- +Validate extension JSON: Error: Field 'native_structures/PhysicsServer3DExtensionMotionCollision': format changed value in new API, from "Vector3 position;Vector3 normal;Vector3 collider_velocity;real_t depth;int local_shape;ObjectID collider_id;RID collider;int collider_shape" to "Vector3 position;Vector3 normal;Vector3 collider_velocity;Vector3 collider_angular_velocity;real_t depth;int local_shape;ObjectID collider_id;RID collider;int collider_shape". +Validate extension JSON: Error: Field 'native_structures/PhysicsServer3DExtensionMotionResult': format changed value in new API, from "Vector3 travel;Vector3 remainder;real_t collision_safe_fraction;real_t collision_unsafe_fraction;PhysicsServer3DExtensionMotionCollision collisions[32];int collision_count" to "Vector3 travel;Vector3 remainder;real_t collision_depth;real_t collision_safe_fraction;real_t collision_unsafe_fraction;PhysicsServer3DExtensionMotionCollision collisions[32];int collision_count". + +The previous type was simply wrong and didn't match the actual C++ definition. Code targeting previous versions should use the updated definition as well. + + +GH-74600 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/AnimatedSprite2D/methods/play'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/AnimatedSprite3D/methods/play'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Animation/methods/compress'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/AnimationPlayer/methods/play'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/AudioStreamPlayer/methods/play'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/AudioStreamPlayer2D/methods/play'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/AudioStreamPlayer3D/methods/play'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/CanvasItem/methods/draw_set_transform'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Curve2D/methods/sample_baked'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Curve2D/methods/sample_baked_with_rotation'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Curve2D/methods/tessellate_even_length'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Curve3D/methods/sample_baked'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Curve3D/methods/sample_baked_with_rotation'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Curve3D/methods/tessellate_even_length'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/DisplayServer/methods/tts_speak'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Font/methods/find_variation'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/GridMap/methods/make_baked_meshes'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Image/methods/save_jpg_to_buffer'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Image/methods/save_webp_to_buffer'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Image/methods/bump_map_to_normal_map'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/PhysicsBody2D/methods/move_and_collide'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/PhysicsBody3D/methods/move_and_collide'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/PhysicsBody3D/methods/test_move'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/RandomNumberGenerator/methods/randfn'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/RenderingServer/methods/environment_set_ambient_light'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/RenderingServer/methods/canvas_item_set_canvas_group_mode'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/RenderingServer/methods/force_draw'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Window/methods/popup_centered_ratio'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Window/methods/popup_centered_clamped'. This means that the function has changed and no compatibility function was provided. + +None of these methods were actually changed, the hash changes only affects GDExtensions, no compatibility workaround exists currently. + + +GH-76413 +-------- +Validate extension JSON: API was removed: classes/AnimationTrackEditPlugin + +This class does nothing and is not useful in any way. + + +GH-69988 +-------- +Validate extension JSON: API was removed: classes/NavigationAgent2D/methods/get_time_horizon +Validate extension JSON: API was removed: classes/NavigationAgent2D/methods/set_time_horizon +Validate extension JSON: API was removed: classes/NavigationAgent2D/properties/time_horizon +Validate extension JSON: API was removed: classes/NavigationAgent3D/methods/get_agent_height_offset +Validate extension JSON: API was removed: classes/NavigationAgent3D/methods/get_ignore_y +Validate extension JSON: API was removed: classes/NavigationAgent3D/methods/get_time_horizon +Validate extension JSON: API was removed: classes/NavigationAgent3D/methods/set_agent_height_offset +Validate extension JSON: API was removed: classes/NavigationAgent3D/methods/set_ignore_y +Validate extension JSON: API was removed: classes/NavigationAgent3D/methods/set_time_horizon +Validate extension JSON: API was removed: classes/NavigationAgent3D/properties/agent_height_offset +Validate extension JSON: API was removed: classes/NavigationAgent3D/properties/ignore_y +Validate extension JSON: API was removed: classes/NavigationAgent3D/properties/time_horizon +Validate extension JSON: API was removed: classes/NavigationObstacle2D/methods/get_rid +Validate extension JSON: API was removed: classes/NavigationObstacle2D/methods/is_radius_estimated +Validate extension JSON: API was removed: classes/NavigationObstacle2D/methods/set_estimate_radius +Validate extension JSON: API was removed: classes/NavigationObstacle2D/properties/estimate_radius +Validate extension JSON: API was removed: classes/NavigationObstacle3D/methods/get_rid +Validate extension JSON: API was removed: classes/NavigationObstacle3D/methods/is_radius_estimated +Validate extension JSON: API was removed: classes/NavigationObstacle3D/methods/set_estimate_radius +Validate extension JSON: API was removed: classes/NavigationObstacle3D/properties/estimate_radius +Validate extension JSON: API was removed: classes/NavigationServer2D/methods/agent_set_callback +Validate extension JSON: API was removed: classes/NavigationServer2D/methods/agent_set_target_velocity +Validate extension JSON: API was removed: classes/NavigationServer2D/methods/agent_set_time_horizon +Validate extension JSON: API was removed: classes/NavigationServer3D/methods/agent_set_callback +Validate extension JSON: API was removed: classes/NavigationServer3D/methods/agent_set_target_velocity +Validate extension JSON: API was removed: classes/NavigationServer3D/methods/agent_set_time_horizon + +Navigation avoidance was reworked entirely. +Migration: TODO + + +GH-????? +-------- +Validate extension JSON: API was removed: classes/FramebufferCacheRD +Validate extension JSON: API was removed: classes/UniformSetCacheRD + +Unsure where these come from; when dumping the interface, these do actually still exist + +GH-76176 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/EditorInterface/methods/get_base_control'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/EditorInterface/methods/get_edited_scene_root'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/EditorInterface/methods/get_editor_main_screen'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/EditorInterface/methods/get_editor_paths'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/EditorInterface/methods/get_editor_settings'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/EditorInterface/methods/get_file_system_dock'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/EditorInterface/methods/get_resource_filesystem'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/EditorInterface/methods/get_resource_previewer'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/EditorInterface/methods/get_script_editor'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/EditorInterface/methods/get_selection'. This means that the function has changed and no compatibility function was provided. + +Functions were made `const`. No adjustments should be necessary. + + +GH-76026 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/EditorScript/methods/get_editor_interface'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/EditorScript/methods/get_scene'. This means that the function has changed and no compatibility function was provided. + +Functions were made `const`. No adjustments should be necessary. + + +GH-76418 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/Object/methods/get_meta_list'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/AnimationNodeStateMachinePlayback/methods/get_travel_path'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/RDShaderFile/methods/get_version_list'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/RenderingServer/methods/global_shader_parameter_get_list'. This means that the function has changed and no compatibility function was provided. + +Return types change, fixed some internal type issues and unnecessarily changed the public type in the process. + + +GH-72749 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/Area2D/methods/get_priority'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Area2D/methods/set_priority'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Area3D/methods/get_priority'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/Area3D/methods/set_priority'. This means that the function has changed and no compatibility function was provided. + +Type changed from `float` to `int`. Previously the `float` values were internally converted to `int`s anyways and the type ways inconsistent with the type of the priority property, which already was `int`. + + +GH-72152 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/MeshInstance3D/methods/create_multiple_convex_collisions'. This means that the function has changed and no compatibility function was provided. + +Added an optional parameter with a default value. No adjustments should be necessary. + + +GH-75759 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/AnimationNode/methods/blend_input'. This means that the function has changed and no compatibility function was provided. +Validate extension JSON: Error: Hash mismatch for 'classes/AnimationNode/methods/blend_node'. This means that the function has changed and no compatibility function was provided. + +Added an optional parameter with a default value. No adjustments should be necessary. + + +GH-75017 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/RichTextLabel/methods/push_list'. This means that the function has changed and no compatibility function was provided. + +Added an optional parameter with a default value. No adjustments should be necessary. + + +GH-76794 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/Tree/methods/edit_selected'. This means that the function has changed and no compatibility function was provided. + +Added an optional parameter with a default value. No adjustments should be necessary. + + +GH-75777 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/SyntaxHighlighter/methods/get_text_edit'. This means that the function has changed and no compatibility function was provided. + +Function was made `const`. No adjustments should be necessary. + + +GH-75250 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/RichTextLabel/methods/push_paragraph'. This means that the function has changed and no compatibility function was provided. + +Added an optional parameter with a default value. No adjustments should be necessary. + + +GH-77143 +-------- +Validate extension JSON: Error: Hash mismatch for 'classes/WorkerThreadPool/methods/wait_for_task_completion'. This means that the function has changed and no compatibility function was provided. + +Changed the return value from `void` to `Error`. No adjustments should be necessary. \ No newline at end of file diff --git a/misc/scripts/validate_extension_api.sh b/misc/scripts/validate_extension_api.sh new file mode 100755 index 00000000000..6cc22c9b632 --- /dev/null +++ b/misc/scripts/validate_extension_api.sh @@ -0,0 +1,60 @@ +#!/bin/bash +set -uo pipefail + +if [ ! -f "version.py" ]; then + echo "Warning: This script is intended to be run from the root of the Godot repository." + echo "Some of the paths checks may not work as intended from a different folder." +fi + +if [ $# != 1 ]; then + echo "Usage: @0 " +fi + +has_problems=0 + +make_annotation() +{ + local title=$1 + local body=$2 + local type=$3 + local file=$4 + if [ ! -v GITHUB_OUTPUT ]; then + echo "$title" + echo "$body" + else + body="$(awk 1 ORS='%0A' - <<<"$body")" + echo "::$type file=$file,title=$title ::$body" + fi +} + +while read -r file; do + reference_file="$(mktemp)" + validate="$(mktemp)" + validation_output="$(mktemp)" + allowed_errors="$(mktemp)" + + # Download the reference extension_api.json + reference_tag="$(basename -s .expected "$file")" + wget -qcO "$reference_file" "https://raw.githubusercontent.com/godotengine/godot-cpp/godot-$reference_tag/gdextension/extension_api.json" + # Validate the current API against the reference + "$1" --headless --validate-extension-api "$reference_file" 2>&1 | tee "$validate" | awk '!/^Validate extension JSON:/' - || true + # Collect the expected and actual validation errors + awk '/^Validate extension JSON:/' - < "$validate" | sort > "$validation_output" + awk '/^Validate extension JSON:/' - < "$file" | sort > "$allowed_errors" + + # Differences between the expected and actual errors + new_validation_error="$(comm "$validation_output" "$allowed_errors" -23)" + obsolete_validation_error="$(comm "$validation_output" "$allowed_errors" -13)" + + if [ -n "$obsolete_validation_error" ]; then + make_annotation "The following validation errors no longer occur (compared to $reference_tag):" "$obsolete_validation_error" warning "$file" + fi + if [ -n "$new_validation_error" ]; then + make_annotation "Compatibility to $reference_tag is broken in the following ways:" "$new_validation_error" error README.md + has_problems=1 + fi + + rm -f "$reference_file" "$validate" "$validation_output" "$allowed_errors" +done <<< "$(find "$( dirname -- "$( dirname -- "${BASH_SOURCE[0]//\.\//}" )" )/extension_api_validation/" -name "*.expected")" + +exit $has_problems