Update docs and build sys, add Example to Actions tests

.github/workflows/build_test.yaml

@@ -41,6 +41,15 @@ jobs:
           cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DASTCENC_ISA_NEON=ON -DASTCENC_ISA_SVE_128=ON -DASTCENC_ISA_SVE_256=ON -DASTCENC_ISA_NONE=ON ..
           make -j4
 
+      - name: Build example
+        run: |
+          export CXX=clang++
+          mkdir build_rel
+          cd build_rel
+          cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DASTCENC_VERSION=refs/pull/${{ github.event.number }}/head ..
+          make -j4
+        working-directory: Utils/Example
+
       - name: Upload binaries
         uses: actions/upload-artifact@v7
         with:
@@ -106,6 +115,15 @@ jobs:
           cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DASTCENC_ISA_NEON=ON DASTCENC_ISA_SVE_128=ON -DASTCENC_ISA_NONE=ON ..
           make -j4
 
+      - name: Build example
+        run: |
+          export CXX=g++-14
+          mkdir build_rel
+          cd build_rel
+          cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DASTCENC_VERSION=refs/pull/${{ github.event.number }}/head ..
+          make -j4
+        working-directory: Utils/Example
+
       - name: Setup Python
         uses: actions/setup-python@v6
         with:
@@ -160,6 +178,15 @@ jobs:
           cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DASTCENC_ISA_AVX2=ON -DASTCENC_ISA_SSE41=ON -DASTCENC_ISA_SSE2=ON -DASTCENC_ISA_NONE=ON ..
           make -j4
 
+      - name: Build example
+        run: |
+          export CXX=clang++
+          mkdir build_rel
+          cd build_rel
+          cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DASTCENC_VERSION=refs/pull/${{ github.event.number }}/head ..
+          make -j4
+        working-directory: Utils/Example
+
       - name: Upload binaries
         uses: actions/upload-artifact@v7
         with:
@@ -222,6 +249,15 @@ jobs:
           cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DASTCENC_ISA_AVX2=ON -DASTCENC_ISA_SSE41=ON -DASTCENC_ISA_SSE2=ON -DASTCENC_ISA_NONE=ON ..
           make -j4
 
+      - name: Build example
+        run: |
+          export CXX=g++
+          mkdir build_rel
+          cd build_rel
+          cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DASTCENC_VERSION=refs/pull/${{ github.event.number }}/head ..
+          make -j4
+        working-directory: Utils/Example
+
       - name: Setup Python
         uses: actions/setup-python@v6
         with:

Docs/Building.md

@@ -334,10 +334,37 @@ Windows packages will use the `.zip` format, other packages will use the
 ## Integrating as a library into another project
 
 The core codec of `astcenc` is built as a library, and so can be easily
-integrated into other projects using CMake. An example of the CMake integration
-and the codec API usage can be found in the `./Utils/Example` directory in the
-repository. See the [Example Readme](../Utils/Example/README.md) for more
-details.
+integrated into other projects. We recommend integrating the project in a way
+that lets you control which version of `astcenc` you are using, as this allows you to manage API version changes.
+
+An basic example of CMake integration and codec API usage can be found in the `./Utils/Example` directory. See the [Example Readme](../Utils/Example/README.md) for more details.
+
+> [!CAUTION]
+> This example is designed to always use the latest main branch so that it
+> stays in sync with any changes we make to the repository. This is not
+> recommended for external production integration because you cannot control
+> which API version your application is using.
+
+### Library API stability across versions
+
+Since version 5.4.0, the library API exposed in `astcenc.h` will follow
+semantic versioning guidelines and remain backwards compatible within each
+major version (`X.*.*`). Any breaking change will result in a major version
+increment.
+
+When updating to a newer major version, callers of the API should expect that
+they will need to update to synchronize with any changes. When a major API
+version makes changes to the API, they will be done in way that deliberately
+causes a compilation failure. This avoids applications hitting failures that
+only occur at runtime.
+
+> [!IMPORTANT]
+> Prior to version 5.4.0, we did not follow this policy and minor versions
+> (`*.X.*`) could introduce API breaks.
+
+When we make changes that modify API entrypoints, we do not usually try to
+maintain backwards compatibility by adding parallel entrypoints to support both
+the new and original behaviors, and prefer to just increment the major version.
 
 ## Configuring a new build machine
 

Source/cmake_core.cmake

@@ -450,8 +450,8 @@ macro(astcenc_set_properties ASTCENC_TARGET_NAME ASTCENC_VENEER_TYPE)
         else()
             target_compile_options(${ASTCENC_TARGET_NAME}
                 PRIVATE
-                    $<${is_clangcl}:-mcpu=native -march=native>
-                    $<${is_gnu_fe}:-mcpu=native -march=native>
+                    $<${is_clangcl}:-march=native>
+                    $<${is_gnu_fe}:-march=native>
                     $<${is_gnu_fe}:-Wno-unused-command-line-argument>)
         endif()
     endif()

Utils/Example/CMakeLists.txt

@@ -1,6 +1,6 @@
 #  SPDX-License-Identifier: Apache-2.0
 #  ----------------------------------------------------------------------------
-#  Copyright 2021 Arm Limited
+#  Copyright 2021-2026 Arm Limited
 #
 #  Licensed under the Apache License, Version 2.0 (the "License"); you may not
 #  use this file except in compliance with the License. You may obtain a copy
@@ -17,10 +17,13 @@
 
 # CMake configuration
 cmake_minimum_required(VERSION 3.15)
+
 include(ExternalProject)
 
 project(astcencoder_example VERSION 1.1.0)
 
+set(ASTCENC_VERSION "main" CACHE STRING "ASTCEncoder git version to import")
+
 # Add the external project and pull out the project directories we need
 
 # The default build is a native build which supports the highest level of SIMD
@@ -32,11 +35,21 @@ project(astcencoder_example VERSION 1.1.0)
 #  *  Add "-DASTCENC_ISA_SSE41:String=ON" and link against "astcenc-sse4.1-static"
 #  *  Add "-DASTCENC_ISA_AVX2:String=ON" and link against "astcenc-avx2-static"
 #  *  Add "-DASTCENC_ISA_NEON:String=ON" and link against "astcenc-neon-static"
+#
+# The DOWNLOAD_COMMAND here is slightly convoluted so that we can point the
+# example build at GitHub PRs in our Actions pipelines. Normal users can remove
+# the DOWNLOAD_COMMAND and UPDATE_COMMAND and set GIT_TAG instead.
 ExternalProject_Add(astcencoder
     GIT_REPOSITORY https://github.com/ARM-software/astc-encoder
-    GIT_TAG main
     CMAKE_CACHE_ARGS -DASTCENC_CLI:STRING=OFF -DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}
-    INSTALL_COMMAND "")
+    DOWNLOAD_COMMAND
+      git clone https://github.com/ARM-software/astc-encoder <SOURCE_DIR> &&
+      cd <SOURCE_DIR> &&
+      git fetch origin ${ASTCENC_VERSION} &&
+      git checkout --detach FETCH_HEAD
+    UPDATE_COMMAND ""
+    INSTALL_COMMAND ""
+)
 
 ExternalProject_Get_property(astcencoder
     SOURCE_DIR)