Fix #224: Add a clang-format that matches the best the OpenSSL coding…

… style. (#241)

This commit adds a `.clang-format` file at the root of the repository. This
`.clang-format` file tries to match the best the OpenSSL coding style.

This commit also reformats the existing code according to that `.clang-format`.

Finally, it adds a new CircleCI job to ensure that the code is well-formatted.

.circleci/config.yml

@@ -240,6 +240,19 @@ jobs:
               fi
             fi
 
+  check-clang-format:
+    docker:
+      - image: cimg/base:2022.12
+    steps:
+      - run:
+          name: Install dependencies
+          command: sudo apt-get update && sudo apt-get install -y clang-format
+      - checkout
+      - run:
+          name: Check coding style using clang-format
+          command: |
+            find . -type f -and '(' -name '*.h' -or -name '*.c' -or -name '*.inc' ')' | xargs clang-format --dry-run --Werror
+
   trigger-downstream-ci:
     docker:
       - image: cimg/base:2020.01
@@ -264,6 +277,7 @@ workflows:
   version: 2.1
   build:
     jobs:
+      - check-clang-format
       - ubuntu:
           name: ubuntu-focal
           context: openquantumsafe

.clang-format

@@ -0,0 +1,81 @@
+# OpenSSL formatting is close to Linux Kernel's , which is close
+# to LLVM's.
+BasedOnStyle: LLVM
+
+# The following rules tries to reproduce the OpenSSL coding style defined
+# in the following document: https://www.openssl.org/policies/technical/coding-style.html
+
+# Chapter 1: Indentation.
+
+## Use 4 space characters, not tabs.
+UseTab: Never
+IndentWidth: 4
+
+## Pre-processor directives use one space for indents, after hash.
+IndentPPDirectives: AfterHash
+
+# This option seems to be broken on clang-format-14, but fixed in clang-format-15.
+# We keep it disabled for now.
+#PPIndentWidth: 1
+
+# Chapter 2: Breaking long lines and strings
+
+## Don’t put multiple statements, or assignments, on a single line.
+AllowShortBlocksOnASingleLine: Never
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortEnumsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AllowAllParametersOfDeclarationOnNextLine: false
+
+## The limit on the length of lines is 80 columns.
+ColumnLimit: 80
+
+# Descendants are always substantially shorter than the parent and are placed substantially to the right.
+AlignAfterOpenBracket: Align
+AlignOperands: Align
+BreakBeforeBinaryOperators: true
+
+# Never break user-visible strings, however, because that breaks the ability to grep for them.
+BreakStringLiterals: false
+
+
+# Chapter 3: Placing Braces and Spaces
+
+SpaceBeforeAssignmentOperators: true
+
+# Use the same indentation level as for the switch statement.
+IndentCaseLabels: false
+
+## […] is to put the opening brace last on the line, and the closing brace first
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterClass: false
+  AfterControlStatement: Never
+  AfterEnum: false
+## There is one special case, however. Functions have the opening brace at the beginning of the next line
+  AfterFunction: true
+  AfterNamespace: false
+  AfterStruct: false
+  AfterUnion: false
+  BeforeCatch: false
+  BeforeElse: false
+  BeforeWhile: false
+
+
+# Chapter 3.1: Spaces
+
+## When declaring pointer data or a function that returns a pointer type, the asterisk goes next to the data or function name, and not the type:
+PointerAlignment: Right
+
+## Do not use multiple consecutive spaces except in comments, for indentation, and for multi-line alignment of definitions, e.g.:
+AlignConsecutiveMacros: AcrossComments
+
+
+# Chapter 9: Macros and Enums
+
+## Macros with multiple statements should be enclosed in a do - while block
+AlignEscapedNewlines: Left

.github/workflows/linux.yml

@@ -5,7 +5,7 @@ on:
     branches: [ '*' ]
   pull_request:
     branches: [ "main" ]
-    
+
 jobs:
 
   linux_intel:
@@ -37,12 +37,14 @@ jobs:
         run: ./scripts/runtests.sh -V
       - name: Verify nothing changes on re-generate code
         run: |
+          apt-get update && apt-get install -y clang-format && \
           git config --global user.name "ciuser" && \
           git config --global user.email "[email protected]" && \
           git config --global --add safe.directory `pwd` && \
           export LIBOQS_SRC_DIR=`pwd`/liboqs && \
           ! pip3 install -r oqs-template/requirements.txt 2>&1 | grep ERROR && \
           python3 oqs-template/generate.py && \
+          find . -type f -and '(' -name '*.h' -or -name '*.c' -or -name '*.inc' ')' | xargs clang-format -i && \
           ! git status | grep modified
       - name: Build .deb install package
         run: cpack

oqs-template/generate.sh

@@ -1,11 +1,14 @@
 #!/bin/bash
 
-cd oqs-template 
+cd oqs-template
 
 rm generate.yml
 
 # Step 1: Obtain current generate.yml from main:
 wget -c https://raw.githubusercontent.com/open-quantum-safe/openssl/OQS-OpenSSL_1_1_1-stable/oqs-template/generate.yml
 
 # Step 2: Run the generator:
-cd .. && python3 oqs-template/generate.py 
+cd .. && python3 oqs-template/generate.py
+
+# Step 3: Run clang-format.
+find . -type f -and '(' -name '*.h' -or -name '*.c' -or -name '*.inc' ')' | xargs "${CLANG_FORMAT:-clang-format}" -i

oqs-template/oqsprov/oqsprov.c/kem_functions.fragment

@@ -1,3 +1,5 @@
+
+// clang-format off
 {%- for kem in config['kems'] %}
 #ifdef OQS_ENABLE_KEM_{{ kem['oqs_alg']|replace("OQS_KEM_alg_","") }}
     KEMBASEALG({{kem['name_group']}}, {{kem['bit_security']}})
@@ -6,4 +8,5 @@
 {%- endfor %}
 #endif
 {%- endfor %}
+// clang-format on
 

oqs-template/oqsprov/oqsprov.c/keymgmt_functions.fragment

@@ -1,3 +1,5 @@
+
+// clang-format off
 {% for sig in config['sigs'] %}
    {%- for variant in sig['variants'] %}
 #ifdef OQS_ENABLE_SIG_{{ variant['oqs_meth']|replace("OQS_SIG_alg_","") }}
@@ -16,4 +18,5 @@
 {%- endfor %}
 #endif
 {%- endfor %}
+// clang-format on