Replacing check-format.pl with clang-format
Another consideration: is clang-format available on all the supported platforms? if not, is it something that impacts the ability of contributors using those platforms to participate in development?
If anyone is curious, I've got this branch here:
https://github.com/nhorman/openssl/tree/sample-clang-format
With a ./clang-format file , a script ./utils/format-style.sh, and the updates to the tree for all the .[ch] files that results from it.
@Tim Hudson, thank you for the reminder
Back when we did the reformatting in early 2015, we went through a series of votes to figure out what approach to take - voting on each branch in turn working backwards. The vote text is below along with the result that gives the history.
-
The 1.0.2 branch will be reformatted to comply with the new coding style
PASS
-
The 1.0.1 and 1.0.0 branches will be reformatted to comply with the new coding style
PASS
-
The 0.9.8 branch will be reformatted to comply with the new coding style
PASS
-
If the coding style is modified so that indents are 4 characters, these indents will use spaces (never combined into tabs)
PASS
-
When reformatting the codebase we will tag before and after automated reformatting, in all branches. Scripts to apply the GNU indent options will also be added to the repository. An announcement will be made a week in advance that this will happen and how it will happen.
PASS
We will perform the code reformat according to our previous decisions from 1st January. This must be completed prior to the next release. As soon as this vote passes (assuming it does) then we will make the announcement that the reformat will be taking place. Unless agreed otherwise between now and then we will use the following GNU indent options. If this produces output that conflicts with our approved style then we will work to address those conflicts later:
-nbad -bap -nbc -bbo -hnl -br -brs -c33 -cd33 -ncdb -ce -ci4 -cli0
-d0 -di1 -nfc1 -i4 -ip0 -l80 -lp -npcs -nprs -npsl -sai -saf -saw -ncs -nsc
-sob -nfca -cp33 -ss -ts0 -il1 -ppi1
FAIL
-
We will give notice of our intention to reformat the code base immediately. One week later we will reformat as per our previous votes using Tim's openssl-format-source script. This will not be before the planned security release but will be immediately before the release of 1.0.2
PASS
You can see the reformat on master both before and after the script was run via these links:
https://github.com/openssl/openssl/commits/master-pre-auto-reformat
https://github.com/openssl/openssl/commits/master-post-auto-reformat
Our rationale at the time (as I recollect) was to make it easy for others to see the impact of the script and to be able to perform checkouts of the state either side of the reformat if that was useful. We also wanted to not impact being able to easily backport fixes to active branches. Note we did not go back to earlier branches than 0.9.8.
I don't care what tool we use for this. I just want something that works almost all of the time. The current script doesn't.
@Neil Horman For historical reference, `indent` is what we used in the Big Source Code Reformat effort back in I can't remember when, but before the 1.1.0 release.
Also, to offer alternative tools to clang-format, I've experimented with the following:
1) indent
2) uncrustify
3) astyle
of the above, uncrustify has similar configurability to clang-format, and seems well maintained, but so far (anecdotally) clang-format seems to be the most widely used tool in this space.
That's true coding style covers not just style (format in terms of spacing etc.) but also coding practices (naming conventions, function exit points etc.) But still having a tool which will reliably handle format will allow us to focus on other details in code review process.
To the prior questions regarding our ability to match our current style document to features in clang-format. I've constructed the following table:
style guide element |
clang-format support option |
PreProcessor indentation (Ch 1) |
IndentPPDirectives |
Breaking long lines and strings (Ch 2) |
ColumnLimit |
K&R Style Brace Placement (Ch 3) |
BraceWrapping |
Use of spaces rather than tabs (Ch 3.1) |
TabWidth/UseTab/various other controls |
Naming (Ch 4) |
None, variable naming is not a formatter controllable element |
Typedefs (Ch 5) |
None, enforcing typedef construction is outside the scope of a formatter, clang-format or check-format.pl |
Function naming/style |
None, This section discusses function complexity and design, and is outside the scope of formatting. Save for the statement regarding the mixing of variable declarations and statements, which is an unclear directive. |
Centralized exit of functions |
none, outside the scope of a formatter, either clang-format or check-format.pl |
Comments (Ch 8) |
clang-format cannot prevent the use of c++ style comments, but commenting can be controlled via the ReflowComment config option as well as other directives. I don't believe that check-format.pl enforces this either |
Macros (ch 9) |
Macro naming is outside the scope of any formatter. Alignment and indentation fall under the ColumnLimit and indentation rules above |
|
Chapters 10-16) Allocating Memory Function return values Editor Modelines Processor Specific Code Portability Expressions Asserts |
outside the scope of the formatter, save for the previously mentioned indentation and alignment rules |
So, generally speaking, for those aspects of our style guide that might be checked with tools like check-format.pl, clang-format appears capable of providing the same checks and corrections. for the other items in our style guide (for instance Memory allocation rules), neither check-format.pl nor clang-format applies, as those elements are less about style than they are about (for lack of a better term) architecture.
But (to editorialize here somewhat), I don't think we should be thinking about a switch to clang-format in an effort to find a better tool to enforce our current style guide. I think instead, we should be looking at a new style format that is driven by what a tool (clang-format or otherwise) can provide for us in such a way that both checks and format corrections can be automated to provide consistency in our code base, consistency being (in my view) the most beneficial aspect of any style.
by way of argument, I'll assert that our existing style isn't really followed. Looking at the head of our master branch, we have about 903206 lines of code in .c and .h files. Running check-format.pl on each of those files, I find a total of 94410 errors reported, suggesting that approximately 10% of our C code violates our style guide as check-format.pl is currently written.
Why is that? anecdotally (fully admitting that I've not done any real counting of the causes), I think the reasons are:
1) Some errors are erroneous - i.e check-format.pl isn't coded to match some element of our current style, or has a bug in which it detects an error that really shouldn't be an error as we have our style documented
2) Sometimes we just decide that following our style isn't worthwhile in some cases (i.e. in a particular case the developer thought it was more readable in a way that didn't match style)
3) Some code pre-dates a subsequent update to the style guide, and was never brought up to date to match that style.
From that, I would conclude that our current situation is that we have a tool for our custom coding style that isn't consistently reflective of our style guide, that can't be used to do mass updates of our code base when our style changes (should we choose to do so), nor do we ourselves follow our coding style consistently (for various and sundry reason).
I think, rather than trying to form a style document that amounts to various guidance about how we like to see our code written, our style guide should instead focus on those elements that any formatting tool can't handle (malloc routines, naming, etc), and let the style be defined by the configuration of the tool we choose. That tool can be run automatically to detect errors on PR's (much like our current check-format CI job, but with a more robust tool than what we currently have), and more importantly be used by developers to automate the process of correcting those style changes.
The impacts are that (if we chose to do a mass code update to match style), there would be backporting impacts for a few releases, and it would of course be a new style to get used to (understanding that, even if we matched our tool config to our current style, there are aspects of our code that aren't covered by our style guide that other formatters would change).
The benefits however are that we would have a tool that is much more widely used and actively developed that our in house checking tools, relieving us of the burden to keep it up to date ourselves, making the process of style checking more robust, and automating the process of correcting style. The results I believe are going to be a far more consistent coding style, which, as I noted above, is really the biggest benefit, that in my view far outweighs any impact that this change might have.
@Frederik Wedel-Heinen Yes, that sounds to me like the way to go.
I’m all for the idea.
However, I also doubt that all of check-format.pl can be performed with clang-format.
So I think the question should be rephrased and the summary should explicitly state which checks should be done with clang-format instead of check-format.pl.
And then whatever checks remains has to be performed with check-format.pl.
Surely a change to the format checker is really only necessary if the syntax of the language has changed, which I don't think has happened. Or: what parts of C99 require major (if any) changes to check-format.pl? I too have had bad experiences with clang-format! I'd be inclined to keep check-format.pl and make any tweaks we think are necessary
I think we still some form of linter as well as a formatter.
At least we can have a 'caller' script that calls both clang-format and current check-format.pl for different checks. And the final goal is to reduce the effort we need to maintain check-format.pl
There's no need to re-invest on tools whose functionality is mainly covered by other tools.
I think changing to a more widely used tool and adjusting our coding guidelines to fit what the tool can handle makes sense. We still have some "quirky" things in place and some flexibility where we should just pick a single approach. Right now we have too many exceptions and too many code format nits that come up during reviews which should be able to be eliminated by automation of formatting and an adjustment of the coding guidelines.
I would perform a general reformat once we settle on what precisely that format should be and apply it to earlier branches to allow for continued easy backfit of code. My view is the benefit comes from consistency and that means automation as we have seen from the last 10 years of not having an automated format approach.
FWIW, if you look at https://github.com/nhorman/openssl/tree/sample-clang-format It appears that clang-format actually handles our un-terminated macros fairly gracefully. I'm looking at commit 315301e96385c3208b7e35c63beb9759b79b56cc, specifially instances of our use of DEFINE_STACK_OF and IMPLEMENT_ASN1_FUNCTIONS as an example.
Most of all, check-format.pl sometimes contradicts our coding style.
When that happens, I have zero regrets waiving the C style checks.
Also, we have macros invocations all over the place that look like a function call, but aren't terminated with ';'. That will confuse any source format checker, including clang-format, to the point that their reports are utter rubbish.
When that happens, I have zero regrets waiving the C style checks.
In my opinion is a completely strict code format checking just breaks readability and usability of the code base. Also due to inevitable weaknesses of the code format tool (it cannot really fully understand the code especially due to our heavy use of macros), it is making our source being dictated by our tools and not by the developers who actually write the code. So I beg to disagree.
@Tomas Mraz I agree this is going to be a significant bump and I fully understand your concerns here. In my opinion the goal here is to have a style/format consistency in the whole source code base. Not running check-format.pl and then deciding wether code should be fixed to make check-format.pl happy or just press c-style waived button. In my opinion, the rigid c-style with no exceptions is a good thing. Think of a C-style/format as a conductor for a coding orchestra. There is no good performance without a conductor.
All this is heading to `Big Source Code Reformat effort 2.0` IMO it should happen in master branch only.
IMO we should not be waving c-style. perhaps the only reason to wave c--style is the case when we adopt 3rd-party code which comes from different project. This should be only exception. c-style waiver as being used now makes c-style policy useless/ineffective.
Please understand than any tool we choose will be imperfect and we will always need exceptions to otherwise fairly strict rules. IMO the current CI job with check-format.pl is good enough for checking. Of course being able to format things would be a nice functionality so I am not opposed to moving to something else eventually although I am not sure this is the most pressing thing we should invest our time in right now. What I would not like to see is committing formatting changes on completely unrelated lines just because the editing/formatting tool forces you to do it. This would make a nightmare when backporting patches, etc.
Agreed, while writing this I recalled this issue:
https://github.com/openssl/openssl/issues/24901
in which you documented several issues that you had run acrossin check-format.pl. If memory serves @Viktor Dukhovni triaged several of the issues, fixed some of them, and determined that the investment of time to fix the remainder likely wasn't worth the effort for the time available ( @Viktor Dukhovni , please correct me here if my recollection is flawed). Assuming my memory is accurate though, if we don't have the time to invest in fixing the tool we have, it seems to me, switching to a tool that is more widely maintained makes sense.
@Neil Horman
check-format.pl is quite buggy... I've to waive the style check more often than not.
I think maintaining both is asking to serve two masters, for which the costs outweigh the benefits. A style should be definitive, and if we need to stray from it, we should document why in the code (clang-format has this feature, which works similarly to how indent does it). As for availability, I agree that check-format.pl is more available than clang-format might be, but I feel like thats the workaround point (i.e. a CI job that checks formatting can easily upload the diff to fix the format errors as an artifact of that job, which developers can just apply if they don't want the tool installed locally).
Why not both? clang-format may not be available to everyone, and there's no reason to get rid of a tool that works for everybody. Is it twice the maintenance burden? Unikely. Will there be conflicts? Probably, but they can be resolved/worked-around. It does sound as though clang-format might be more limited in it's functionality.
I vote for adopting clang-format for the checks in check-format.pl that can be implemented using that. Please refer to my comment in the thread.
I'd really like to see such things start as a discussion before going straight to a vote. Votes don't allow you to just post comments without having to make a choice. I believe there are reasons why check-format.pl exists, and why that was chosen over existing formatting tools (I think because it was too difficult to get other tools to do the checks we wanted). I don't know if those reasons still apply. It is the wrong way around to decide to go to some other tool first before evaluating it. If we think check-format.pl no longer meets our needs we should write down what our needs are and evaluate the alternative(s) to determine which one best achieves those needs.
BTW "there is an opportunity to replace it with a more recent tool."...check-format is not even really that old (it was first added in 2020)
If we're going for absolute consistency, I'd rather force a line break after the function return type.
@Sasha Nedvedicky I strongly prefer to see consistency here too. Pick one approach and stick to it. We have a lot of the code where the coding style is such that we get personal preferences for approaches that differ which are throughout the code. Picking on consistent style does lead to cleaning looking code.
@Richard Levitte I prefer consistency here. I believe we should choose one and stick to it. I prefer the variant for function `sub()` as it is make navigation in source code easier (finding function definition is easy just /^sub). However consistency takes precedence at least for me.
@Sasha Nedvedicky
I see nothing wrong with accepting both, mind you... sometimes, our function signatures are really very long, and breaking after the return type has precedents (it's standard in GNU coding recommendations, for example).
No I'm not sure at all however the check-format.pl we use is quite liberal. for example both those two quite different styles below are accepted with no issues:
int add(int a, int b)
{
return a + b;
}
int
sub(int a, int b)
{
return a - b;
}Are you absolutely sure all the existing rules (or at least the important ones) enforced by check-format.pl are doable with clang-format?
A technical note: clang-format, like any formatter, is limited to exactly that, formatting. They are usually not designed to enforce code ordering rules, or to reorder code (such as moving all variable declarations to the start of a block). That's simply out of their scope. To enforce such things, we'd need some sort of linter with that sort of capability, in addition to a formatter.
I'm for clang-format although there does not seem to be way to ask clang-format to restrict variable declaration. I could not figure out a way to tell clang-format not to allow variable declaration in the middle of the code block.
Replacing check-format.pl with clang-format
proposal by Sasha Nedvedicky Closed Mon 23 Jun 2025 9:00PM
The poll indicates there is 2/3 support for switching to clang-format. On the other hand, 25% committers did not cast their vote. So I would interpret the result as mild interest. Perhaps we need to come up with a more detailed/appealing plan to convince the undecided to cast their vote.
thanks for your participation.
Moving from ANSI-C to C-99 requires us to update C-style. For example, we are already aware that we need to impose some restrictions on where variables can be declared. The C-99 standard is too liberal because it allows variable declaration anywhere. For OpenSSL we might want to restrict the C-99 freedom here and allow variable declarations at the start of the block or inside of conditionally compiled sections (see discussion here). There might be more C-99 constructs that we will need to ban/restrict. Let's leave those for a separate poll/discussion. This decision is about replacing util/check-format.pl with clang-format.
My reasoning about using a clang-format instead of perl script goes as follows:
Adoption of C-99 requires an update to C-style, which will require updating check-format.pl. instead of fixing Perl code, there is an opportunity to replace it with a more recent tool.
Unlike check-format.pl, the clang-format can also format the code to match C-style
clang-format seems to play nicely with git
clang-format comes with plugins for various editors (emacs, vim, VS-code, ...)
Neil and Andrew gave a clang-format try already and the tool can get confused (see details here), but I still think it is a way to go.
In this poll, I'd like to select the tool that will check and format C-style the follow-up polls will be taking decisions on updating the C-style.
Results
| Results | Option | Votes | % of votes cast | % of eligible voters | |
|---|---|---|---|---|---|
| let's go for clang-format | 8 | 62 | 42 | ||
| keep using check-format.pl | 2 | 15 | 11 | ||
| What other tool to check (and format) sources you suggest? | 3 | 23 | 16 | ||
| Not voted | 6 | 32 |
clang-format is part of clang ,for which the supported host and target environments are:
AArch64
AMDGPU
ARM
AVR
BPF
Hexagon
Lanai
LoongArch
Mips
MSP430
NVPTX
PowerPC
RISCV
Sparc
System
ZVE
WebAssembly
X86
XCore
Which covers all of our primary, secondary and community platforms, as well as the majority of our unadpoted platforms.
I think the direct question is how do we support users that just don't want to install clang, and my thought would either be the use of a containerized environment, or a github action based on an issue_comment trigger, in which users could simply add a comment with a keyword like /format in a PR, which would trigger CI to produce a patch that was attached by the CI as a subsequent comment.