Add a convenience script for consistent astyle formatting (#1861)

* Add script to format code in a CI container

* Update CONTRIBUTING.md to document script
---------

Signed-off-by: Spencer Wilson <[email protected]>

CONTRIBUTING.md

@@ -26,11 +26,13 @@ them before the final "Review" stage.
 
 This project has adopted a slightly modified [Google code formatting style](https://astyle.sourceforge.net/astyle.html#_style=google) for the core components
 of the library as documented in the [style template](.astylerc).
-
-To check adherence of any new code to this, it therefore is highly recommended to
-run the following command in the project main directory prior to finishing a PR:
-
-    find src tests -name '*.[ch]' | grep -v '/external/' | grep -v 'kem/.*/.*/.*' | grep -v 'sig/.*/.*/.*' | xargs astyle --dry-run --options=.astylerc | grep Format
+The `astyle` tool is used to check formatting in CI.
+Due to variations in behaviour across version and platforms, it is possible to encounter CI failures even if code has been locally formatted with `astyle`.
+To assist with this inconvenience, we provide a convenience script which runs `astyle` in the same Docker image that we use for the CI checks:
+```bash
+LIBOQS_DIR=<liboqs directory> ./scripts/format_code.sh
+```
+This script has been tested on x86\_64 Ubuntu and arm64 macOS. Contributions for other platforms are welcome and appreciated!
 
 ### Running CI locally
 

scripts/format_code.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+
+# SPDX-License-Identifier: MIT
+
+# usage: LIBOQS_DIR=<liboqs dir> ./scripts/format_code.sh
+
+arch=$(uname -m)
+
+# tested on Ubuntu 22 / x86_64 and macOS 13 / arm64
+if [ "$arch" != "x86_64" ] && [ "$arch" != "arm64" ]
+then
+	echo "This script does not currently support systems where \`uname -m\` returns $arch."
+	exit 1
+fi
+
+if [ ! -d "$LIBOQS_DIR" ]
+then
+	echo "Please set the environment variable LIBOQS_DIR to point to your liboqs directory."
+	exit 1
+fi
+
+docker run --rm -v"$LIBOQS_DIR":/root/liboqs -w /root/liboqs openquantumsafe/ci-ubuntu-focal-$arch:latest ./tests/run_astyle.sh --no-dry-run

tests/run_astyle.sh

@@ -3,8 +3,14 @@
 
 rv=0
 
+if [ "$1" = "--no-dry-run" ]; then
+	dryrun=""
+else
+	dryrun="--dry-run"
+fi
+
 # check style of non-external code:
-find src tests -name '*.[ch]' | grep -v '/external/' | grep -v 'kem/.*/.*/.*' | grep -v 'sig/.*/.*/.*' | xargs astyle --dry-run --options=.astylerc | grep Format
+find src tests -name '*.[ch]' | grep -v '/external/' | grep -v 'kem/.*/.*/.*' | grep -v 'sig/.*/.*/.*' | xargs astyle $dryrun --options=.astylerc | grep Format
 if [ $? -ne 1 ]; then
    echo "Error: Some files need reformatting. Check output above."
    rv=-1