Move CI to GitHub Actions (#223)

* Implement GitHub Pages site to show files generated from latest commit to main. * Fix docrev and revision history for upcoming release. * Update README. * Delete outdated TODO.
KhronosGroup · Feb 1, 2025 · 8754dbe · 8754dbe
1 parent f86eaf1
commit 8754dbe
Show file tree

Hide file tree

Showing 8 changed files with 147 additions and 143 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -24,46 +24,43 @@ on:
 
 jobs:
   build-specs:
-    name: Build KTX and KTX Fragments specifications
+    name: Build KTX File Format and KTX Fragment URI specifications
     runs-on: ubuntu-latest
 
-    env:
-      GIT_LFS_SKIP_SMUDGE: 1
-      WERROR: ON
-
     steps:
     - uses: actions/checkout@v4
 
-#    - uses: ruby/setup-ruby@v1
-#      with:
-#        ruby-version: 2.7
+    - name: Install Asciidoctor
+      run: sudo apt-get install -y asciidoctor
+
+    - name: Build specs
+      run: make ghpages
 
-    - uses: reitzig/[email protected]
+    - name: Upload generated files for GitHub Pages
+      id: deployment
+      uses: actions/upload-pages-artifact@v3
       with:
-        version: 2.0.18
-
-#    - name: Force fetch provoking tag's annotation.
-#      # Work around https://github.com/actions/checkout/issues/290.
-#      if: github.ref_type == 'tag'
-#      run: git fetch -f origin ${{ github.ref }}:${{ github.ref }}
-
-    - run: make
-
-#    - name: Upload To Pages
-#      uses: softprops/action-gh-release@v1
-#      if: github.event_name == 'push' && github.ref_type == 'tag'
-#      with:
-#        draft: true
-#        prerelease: true
-#        files:  KTX-Software-${{env.KTX_VERSION}}-Android.zip*
-#      env:
-#        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-  # Deploy job
+        path: out/ghpages/
+
+  generate-switches:
+    name: Generate and test compile format conversion switches.
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Generate switches
+      run: make switches
+
+    - name: Test compile switches
+      run: make testswitches
+
   deploy:
     name: Deploy to GitHub Pages
     # Add a dependency to the build job
     needs: build-specs
+    # Only deploy when building `main`.
+    if: github.ref == 'refs/heads/main'
 
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
     permissions:

diff --git a/.travis.yml b/.travis.yml
diff --git a/Makefile b/Makefile
@@ -1,14 +1,17 @@
 # Copyright (c) 2014-2017 The Khronos Group Inc.
 # Copyright notice at https://www.khronos.org/registry/speccopyright.html
 
-# Use docs for compatibility with GitHub pages.
 out=out
-ktxspec=$(out)/ktxspec.v2
-ktxfrag=$(out)/ktx-frag
+out.specs = $(out)/specs
+out.switches = $(out)/switches
+out.ghpages = ${out}/ghpages
+
+ktxspec = $(out.specs)/ktxspec.v2
+ktxfrag = $(out.specs)/ktx-frag
 
 all: $(ktxspec).html $(ktxfrag).html #$(ktxspec).pdf
 
-regdoc: $(out)/ktx-media-registration.txt
+regdoc: $(out.specs)/ktx-media-registration.txt
 
 ktx_inlined_images := icons/ktx_favicon.ico \
                   images/cubemap_coord_system.svg \
@@ -25,22 +28,37 @@ ktx_sources := ktxspec.adoc \
            ktx-media-registration.adoc \
            license.adoc \
            khronos.css \
-           $(out) \
            $(ktx_inlined_images) \
            docinfo.html
 
 frag_inlined_images := icons/ktx_favicon.ico
 
 frag_sources := ktx-frag.adoc \
                 khronos.css \
-                $(out) \
                 $(frag_inlined_images) \
                 docinfo.html
 
-$(ktxspec).html: $(ktx_sources)
+ghpages.index := $(out.ghpages)/index.html
+ghpages.ktxspec := $(out.ghpages)/ktxspec.v2.html
+ghpages.ktxfrag := $(out.ghpages)/ktx-frag.html
+
+# For GitHub CI to build GitHub Pages site.
+ghpages: $(ghpages.index) $(ghpages.ktxspec) $(ghpages.ktxfrag) images/khronos.svg images/ktx.svg
+
+
+switches := vkFormat2dxgiFormat.inl \
+              vkFormat2glInternalFormat.inl  \
+              vkFormat2mtlFormat.inl \
+              vkFormat2glFormat.inl \
+              vkFormat2glType.inl
+switches := $(addprefix ${out.switches}/,${switches})
+
+switches: $(switches)
+
+$(ktxspec).html: $(ktx_sources) | $(out.specs)
 	asciidoctor --trace -v --failure-level INFO -r ./inline-images.rb -r ./formats-include.rb -D $(dir $@) -o $(notdir $@) $<
 
-$(ktxfrag).html: $(frag_sources)
+$(ktxfrag).html: $(frag_sources) | $(out.specs)
 	asciidoctor --trace -v --failure-level INFO -r ./inline-images.rb -D $(dir $@) -o $(notdir $@) $<
 
 $(ktxspec).pdf:
@@ -66,15 +84,33 @@ end
 endef
 
 # Creates pure-text version of media-registration for submission to IANA.
-$(out)/ktx-media-registration.txt: ktx-media-registration.adoc $(out)
+$(out.specs)/ktx-media-registration.txt: ktx-media-registration.adoc | $(out.specs)
 	ruby -e '$(pure.rb)' $< >$@
 
+$(ghpages.index): ghpages-index.adoc
+	asciidoctor --trace -v --failure-level INFO -r ./inline-images.rb -D $(dir $@) -o $(notdir $@) $<
+
+${out.ghpages}/%.html: ${out.specs}/%.html
+	cp $< $@
+
+# &: is the "grouping separator" added in GNU make 4.3 to tell Make that
+# the command generates all listed targets. Earlier versionsa treat this
+# the same as the : separator and will issue the command for each target.
+$(switches) &: formats.json formats.schema.json generate_format_switches.rb | $(out.switches)
+	./generate_format_switches.rb $(out.switches)
+
+testswitches: $(switches)
+	cd switch_test; $(MAKE) switches_dir=../$(out.switches)
+
 $(out):
 	mkdir -p $@
 
+$(out.specs) $(out.switches): | $(out)
+	mkdir -p $@
+
 clean:
 
 clobber: clean
-	rm -rf $(out)
+	rm -rf $(out.specs) $(out.switches) $(out.ghpages) $(out)
 
 # vim: ai noexpandtab tw=72 ts=4 sw=4
diff --git a/README.md b/README.md
@@ -5,16 +5,20 @@
 KTX is a file format that can be used for storing GPU-ready texture data (with cubemaps, mip levels, etc).
 Like DDS but with more features and more formal specification. It supports Basis Universal transcodable formats and supercompression which can yield JPEG-sized universal textures. glTF will use Basis Universal textures in KTX v2 containers.
 
-Click to see the latest published versions of the [KTX File Format Specification](https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html) 
+Click these links to see the latest published versions of the
+[KTX File Format Specification](https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html) 
 or the [KTX Fragment URI Specification](https://registry.khronos.org/KTX/specs/2.0/ktx-frag.html)
-from the Khronos KTX Registry (they look much better than the ersatz views provided by GitHub) or run
+from the Khronos KTX Registry, visit the project's
+[GitHub Pages](https://github.khronos.org/KTX-Specification/) to see formatted
+versions of the latest commits to `main` (both options look much better than
+the ersatz views provided by GitHub) or run
 
-```.bash
+```bash
 make
 ```
 
 in a Unix-like environment with [AsciiDoctor](https://asciidoctor.org/docs/install-toolchain/)
-installed to generate the publishable specs. They are the files `out/ktxspec.v2.html` and `out/ktx-frag.html`.
+installed to generate the publishable specs. They are the files `out/specs/ktxspec.v2.html` and `out/specs/ktx-frag.html`.
 Everything needed is inlined.
 
 The canonical KTX spec. text is in the file `ktxspec.adoc`. The canonical fragment URI spec. text is in the file `ktx-frag.html`.
@@ -29,38 +33,16 @@ To ensure correct mappings from Vulkan's `VkFormat` to other GPU APIs, this repo
 - [JSON database](formats.json) ([schema](formats.schema.json)) with mappings to OpenGL, Direct3D, and Metal enums.
 - [Switch-case generator](generate_format_switches.rb) that produces 5 files with simple C-like case-return statements.
   > **Usage:** `./generate_format_switches.rb [<out_dir>]`
-- [Compile test of the case statements](switch_test/vk2gl.c) that serves as an example of use.
-
-### <a id="kwexpansion"></a>$Date$ keyword expansion
-
-A few auxiliary  files have `$Date$` keywords. If you care about having
-the proper dates shown on files in your workspace, you **must** follow the
-instructions below.
-
-$Date$ keywords are expanded via a smudge & clean filter. To install
-the filter, issue the following commands in the root of your clone.
-
-On Unix (Linux, Mac OS X, etc.) platforms and Windows using Git for Windows'
-Git Bash or Cygwin's bash terminal:
-
-```bash
-./install-gitconfig.sh
-rm TODO.md
-git checkout TODO.md
-```
-
-On Windows with the Command Prompt (requires `git.exe` in a directory
-on your %PATH%):
-
-```cmd
-install-gitconfig.bat
-del TODO.md
-git checkout TODO.md
-```
-
-The first command adds an [include] of the repo's `.gitconfig` to the
-local git config file `.git/config`, i.e. the one in your clone of the repo.
-`.gitconfig` contains the config of the "dater" filter. The remaining
-commands force a new checkout of the affected files to smudge them with the
-date. These two are unnecessary if you plan to edit these files.
+- [Compile test of the case statements](switch_test/vk2gl.c) that serves as an example of use. To try the compile test do
+
+ ```bash
+ cd switch_test
+ make
+ ```
+ or
+
+ ```bash
+ make testswitches
+ ```
+
 
diff --git a/TODO.md b/TODO.md
diff --git a/ghpages-index.adoc b/ghpages-index.adoc
@@ -0,0 +1,28 @@
+= KTX Specifications (Latest Committed Versions)
+:author: Mark Callow
+:author_org: Edgewise Consulting
+:description: Main page for KTX GitHub pages site
+//:docrev: 3
+//:ktxver: 2.0
+//:revnumber: {ktxver}.{docrev}
+//:revdate: {docdate}
+//:version-label: Version
+:lang: en
+:docinfo1:
+:doctype: article
+:encoding: utf-8
+:stylesheet: khronos.css
+:imagesdir: images
+:data-uri:
+
+:url-khr-reg: https://registry.khronos.org
+:url-khr-ktx: {url-khr-reg}/KTX
+
+These generated documents reflect the latest commits to the main branch
+of the specification source repo. For latest released (published) versions
+see {url-khr-ktx}[the KTX Registry].
+
+* link:ktxspec.v2.html[KTX v2.0 Specification]
+* link:ktx-frag.html[KTX Fragment URI Specification]
+
+
diff --git a/ktxspec.adoc b/ktxspec.adoc
@@ -2,7 +2,7 @@
 :author: Mark Callow
 :author_org: Edgewise Consulting
 :description: Specification of a container format for GPU textures.
-:docrev: 3
+:docrev: 4 (draft)
 :ktxver: 2.0
 :revnumber: {ktxver}.{docrev}
 :revdate: {docdate}
@@ -2455,11 +2455,15 @@ include::appendices/vendor-metadata.adoc[]
                                       GL formats mapping.
                                     - Increase document width from
                                       55em to 60em.
-|      {docrev}     |  {revdate}  | - Fix `typeSize` for formats with
+|          3       |  2024-02-20  | - Fix `typeSize` for formats with
                                       `_nPACKxx` suffix.
                                     - Prohibit YCbCr 2-plane 444 formats
                                       recently added to Vulkan.
                                     - Allow `A8B8G8R8*PACK32` formats.
+|      {docrev}     |  {revdate}  | - Relax restrictions on
+                                      `colorPrimaries` values.
+                                    - Fix bit size of descriptorType in
+                                      dfdBlock.
                                     - Do not use "default" in describing
                                       the object coordinate systems
                                       commonly used with OpenGL and