Skip to content

Commit 35aa2e6

Browse files
sherry-yuanpcolberg
authored andcommitted
Add documentation for running clang-format
Document which clang version to run to avoid workflow failure, clang-format git integration as well installation instruction.
1 parent 7e4d348 commit 35aa2e6

File tree

1 file changed

+26
-0
lines changed

1 file changed

+26
-0
lines changed

CONTRIBUTING.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,11 +126,37 @@ branch that is checked out in a separate worktree.
126126
git log --stat -p aaaaaa...bbbbbb
127127
```
128128
129+
## Polishing a change
130+
131+
Prior to pushing your change, remember to run [clang-format] on the `.c`,
132+
`.cpp`, and `.h` files, since the [clang-format workflow] may fail otherwise.
133+
You can do so by running the following command.
134+
135+
```
136+
./scripts/clang-format.sh --verbose
137+
```
138+
139+
To match the exact formatting expected by the [clang-format version in the
140+
workflow], you will need to obtain [clang version 13.0.0] and add its `bin`
141+
directory to `PATH`. If you are using RHEL/CentOS or SLES/openSUSE, try
142+
installing one of the `clang+llvm-13.0.0-x86_64-linux-gnu-ubuntu-*.tar.xz`
143+
that is compatible with the libc and libstdc++ versions provided by your
144+
distribution.
145+
146+
If you wish to format a committed or staged file, you can use clang-format git
147+
integration, [git-clang-format]. The main benefit of `git clang-format` is the
148+
ability to format a specific commit or only staged files.
149+
129150
[Intel organization]: https://github.com/intel
130151
[Intel® FPGA Runtime for OpenCL™ Software Technology]: https://github.com/intel/fpga-runtime-for-opencl
152+
[clang version 13.0.0]: https://github.com/llvm/llvm-project/releases/tag/llvmorg-13.0.0
153+
[clang-format version in the workflow]: https://github.com/intel/fpga-runtime-for-opencl/blob/fc99b92704a466f7dc4d84bd45d465d64d03dbb0/container/ubuntu-20.04-clang/Dockerfile#L9
154+
[clang-format workflow]: https://github.com/intel/fpga-runtime-for-opencl/blob/fc99b92704a466f7dc4d84bd45d465d64d03dbb0/.github/workflows/clang-format.yml
155+
[clang-format]: https://clang.llvm.org/docs/ClangFormat.html
131156
[create a forked repository]: https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository
132157
[fork and pull model]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models#fork-and-pull-model
133158
[git worktree]: https://git-scm.com/docs/git-worktree
159+
[git-clang-format]: https://github.com/llvm/llvm-project/blob/9e634b35ff51d0eb2b38013111491e88bdbae388/clang/tools/clang-format/git-clang-format
134160
[pull requests]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
135161
[remote repositories]: https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes
136162
[runtime repository]: https://github.com/intel/fpga-runtime-for-opencl

0 commit comments

Comments
 (0)