clang-format-node

Node repackaging(wrapping) of the clang-format native binary inspired by 'angular/clang-format'.🐉

This package intends to release a new npm package for every latest release of the clang-format. It checks for the latest LLVM release every week, builds clang-format using its own pipeline, and makes a pull request. All processes are run automatically. If you are interested in build process, take a look at .github/workflows/llvm-build-bump-pr.yml

[!IMPORTANT]

Please participate in the issue regarding the introduction of a glob pattern. Click here.

Why I started this project

'angular/clang-format' is no longer maintained. (See #79 #82 #83) Nevertheless, new versions of clang-format continue to be released. Bugs are fixed, and new features are added. However, using clang-format directly in a Node.js environment without any support can be somewhat cumbersome. So I decided to make a new, maintained one.

Note that some feautures from 'angular/clang-format' are not included in this package. Specifically check-clang-format and git-clang-format are not used. There are a few reasons for this. Both commands rely on Python, so if you haven't installed Python, they cannot be executed. Many people would prefer if this package worked without dependencies beyond Node.js. So, this package relies only on Node.js. See the Migration for alternative methods to check-clang-format and git-clang-format.

Supported

OS Platforms and Architectures

It supports ALL Tier1 and some Tier2 platforms of Node.js. Note that the functionality cannot be guaranteed on platforms which is not mentioned below.

(To see the full list of platforms supported by Node.js, click here.)

[!TIP]

1. If your platform isn't yet supported, you can build the clang-format native binary from the latest upstream clang sources. Refer to docs/llvm-build-linux.sh and .github/workflows/llvm-build-bump-pr.yml for the build scripts for Linux Shell and GitHub Actions, respectively.

2. Or you can download clang-format native binary from LLVM release assets that match your operating system platform and architecture like the lists below.

   • clang+llvm-18.1.7-aarch64-linux-gnu.tar.xz
   • clang+llvm-18.1.7-armv7a-linux-gnueabihf.tar.gz
   • clang+llvm-18.1.7-powerpc64-ibm-aix-7.2.tar.xz
   • clang+llvm-18.1.7-x86_64-pc-windows-msvc.tar.xz
   • and more...

Node.js

The official support for Node.js version 16 and above has been confirmed through testing.

[!NOTE]

However, this package does not utilize the latest features of Node.js and is transpiled using Babel. Therefore, it is expected to work on versions significantly lower than the officially supported ones. (ex. "node": ">= 0.7.10") Consequently, if the current package operates on a version of Node.js that is lower than the officially supported version, it should be perfectly fine to use.

GitHub Actions Runner Images

If you want to use clang-format-node in continuous integration (CI), You can use GitHub Actions. The following basic runner images are compatible(available) with clang-format-node.

However, the following basic runner images are NOT compatible(available) with clang-format-node. It's because the dependencies for LLVM's latest release version are not compatible with the following images.

Docker(Build) Images

I used the following Images to build clang-format excuatable binaries.

[!TIP]

If you want to see which software is included in GitHub Actions runner, click here and refer to the 'Included Software' column.

Installation

global

npm install -g clang-format-node

yarn global add clang-format-node

local(devDependencies)

npm install --save-dev clang-format-node

yarn add --dev clang-format-node

Usages

If you want to learn more about clang-format itself, see the clang-format style options.

[!TIP]

clang-format can take multiple files as arguments.

npx clang-format -n -Werror file1.cpp file2.cpp src/file3.cpp

Basic

Global

clang-format [options] [@<file>] [<file> ...]

Local

Use npx to run a locally installed package.

npx clang-format [options] [@<file>] [<file> ...]

Frequently used commands

1. --version: Check the version of clang-format.

   npx clang-format --version

   Output example

   clang-format version 18.1.8 (https://github.com/llvm/llvm-project 3b5b5c1ec4a3095ab096dd780e84d7ab81f3d7ff)

   • https://github.com/llvm/llvm-project: Git repository URL for the LLVM project, which includes Clang.
   • 3b5b5c1ec4a3095ab096dd780e84d7ab81f3d7ff: The commit hash of the Git repository where the source code for that version is stored. This hash allows you to precisely trace which source code version was used to generate clang-format.

2. --help: Help view additional options.

   npx clang-format --help

3. --dry-run or -n: Makes an WARNING when example.cpp is not correctly formatted.

   --dry-run and -n options are equivalent.

   npx clang-format --dry-run example.cpp

   npx clang-format -n example.cpp

4. -Werror --dry-run or -Werror -n: Makes an ERROR when example.cpp is not correctly formatted.

   Similar to eslint or prettier --check commands.

   --dry-run and -n options are equivalent.

   npx clang-format -Werror --dry-run example.cpp

   npx clang-format -Werror -n example.cpp

5. -i: Automatically fix unformatted files.

   Similar to eslint --fix or prettier --write commands.

   npx clang-format -i example.cpp

Glob patterns

Unfortunately, there is no way to apply clang-format recursively. *.cpp will only match files in the current directory, not subdirectories. Even **/* doesn't work.

So, you need to use the find command in Linux. If you are a Windows user, use git bash. then you can use the find command. The find command recursively searches through directories.

It is simple but can produce an error if the Argument list is too long. In that case, use xargs

Basic

To recursively search for all .cpp files in the current directory, use:

npx clang-format $(find . -name "*.cpp")

If the argument list is too long, use xargs. And if file names contain spaces or special characters, use -print0 and -0 options. -print0 makes find output file names separated by null characters (\0), and -0 tells xargs to correctly handle these null-separated file names.

find . -name "*.cpp" -print0 | xargs -0 npx clang-format

With regular expressions

To recursively search for all .cpp and .h files in the current directory using a regular expression, use:

npx clang-format $(find . -regex ".*\.\(cpp\|h\)")

With negation patterns

To exclude excluded_file.cpp from the .cpp files, use:

npx clang-format $(find . -name "*.cpp" ! -name "excluded_file.cpp")

.clang-format-ignore

You can create .clang-format-ignore files to make clang-format ignore certain files. A .clang-format-ignore file consists of patterns of file path names. It has the following format:

• A blank line is skipped.
• Leading and trailing spaces of a line are trimmed.
• A line starting with a hash (#) is a comment.
• A non-comment line is a single pattern.
• The slash (/) is used as the directory separator.
• A pattern is relative to the directory of the .clang-format-ignore file (or the root directory if the pattern starts with a slash). Patterns containing drive names (e.g. C:) are not supported.
• Patterns follow the rules specified in POSIX 2.13.1, 2.13.2, and Rule 1 of 2.13.3.
• A pattern is negated if it starts with a bang (!).

To match all files in a directory, use e.g. foo/bar/*. To match all files in the directory of the .clang-format-ignore file, use *. Multiple .clang-format-ignore files are supported similar to the .clang-format files, with a lower directory level file voiding the higher level ones.

Use with husky and lint-staged

Ensuring that changes to your code are properly formatted is an important part of your development workflow. Use husky and lint-staged for your continuous integration process.

husky (v8.x)

# .husky/pre-commit

npx lint-staged

lint-staged (v15.x)

1. Check

   /* package.json */
   
   {
     // ...
     "lint-staged": {
       "*.{c,cpp,h}": "npx clang-format -Werror -n",
     }
     // ...
   }

2. Fix

   /* package.json */
   
   {
     // ...
     "lint-staged": {
       "*.{c,cpp,h}": "npx clang-format -i",
     }
     // ...
   }

[!TIP]

If example1.cpp and example2.c are staged, then npx clang-format -Werror -n example1.cpp example2.c will be excuted.

Migration from 'angular/clang-format'

check-clang-format

This package only uses native clang-format features to check formatting. The following commands will produce an error if the target files are not correctly formatted. So use them with husky and lint-staged. (--dry-run and -n options are equivalent.)

npx clang-format -Werror --dry-run example.cpp

npx clang-format -Werror -n example.cpp

git-clang-format

Use husky and lint-staged for the pre-commit hook instead. See Use with husky and lint-staged for details.

Contributing

Thanks for having attention to this package.🙇‍♂️ Issues and PRs are always welcome.🎉

I recommend you to read the guides on LLVM and clang-format mentioned in issues tab before contributing.

Installation

1. Fork it.

2. Clone it to your local directory. (Git is required.)

   git clone https://github.com/lumirlumir/npm-clang-format-node.git

3. Move to the npm-clang-format-node directory.

   cd npm-clang-format-node

4. Install npm packages. (Node.js is required.)

   npm install

5. Edit codes.

6. Create my-branch branch.

   git switch -c my-branch

7. Commit your changes. (husky and lint-staged will lint and test your changed files!)

   git commit -am "commit type: title"

8. Push them to your remote branch.

9. Submit a pull request.👍

About os.platform() and os.arch() in Node.js

os.platform()

The return value is equivalent to process.platform.

os.arch()

The return value is equivalent to process.arch.

[^1]: le stands for little-endian, but the os.arch() function does not distinguish between endianness and returns a single value.

Build process

Some packages for cross-compilation have been deprecated, making it difficult to make build processes directly, so cross-compilation is not used. Instead, I utilize QEMU and Docker to build cross-compiled binaries.

If you want to learn more about the images I used, see Docker(Build) Images

Versioning

This project adheres to Semantic Versioning.

The BREAKING CHANGES, features and bug fixes from LLVM will be reflected in this package.

The release title includes the LLVM version, like v1.0.0 (llvmorg-18.1.8). See .clang-format-version to check the exact current LLVM version.

Change Log

See CHANGELOG.md

License

MIT under LLVM Apache License 2.0