Repository files navigation

Utilities for converting from C/C++ include guards to #pragma once andback again.

Include guards suck. They're tiring to type and tedious to update. Worse, thetask of updating boilerplate leaves room for copy/paste errors, or othermistakes. #pragma once is simpler and less error prone. That's why you shouldconvert to #pragma once.

Alas, though #pragma once is available on all the most commonly usedcompilers, it's not available onevery compiler. Perhaps one day you'll addsupport for a platform with a barebones compiler with no support for #pragmaonce and you'll have to convert back. That's ok. It's easy!

There are three main tools provided by guardonce:

1. checkguard helps find any broken include guards you may already have inyour project. These should be addressed before converting.

2. guard2once converts files with include guards into files with #pragmaonce directives. This ensures your entire project is consistently using #pragmaonce.

3. once2guard converts files with #pragma once directives back into fileswith include guards. This ensures your entire project is consistently usinginclude guards.

First, check your project for broken headers. To recursively search yourproject directories for the names of all files that lack proper include guards,use the following command, substituting your project's directory for thequoted string:

checkguard -r "source_directory"

By default, checkguard is very forgiving. It accepts either #pragma once oranything that looks like an include guard. If you know that all your guardsshould match some format, you can be more strict by using-p to specifya pattern to check against.

If certain files are not supposed to have include guards, feel free to leavethem be. Files without include guards are ignored by this next step.

Now, all that remains is converting the headers to use #pragma once:

guard2once -r "source_directory"

You're done! Double check that the result matches your expectations and startusing #pragma once in your new code. Know that if you ever need to switch back,it's as simple as:

once2guard -r "source_directory"

If the default guard style doesn't appeal to you, there are a few options tocustomize it. Maybe take a look throughonce2guard --help or check out awalkthrough for some examples.

Whether you use Python 2 or Python 3, these tools can be installed with pip.Runpython -m pip install guardonce and you're off to the races.

If you'd rather not use pip, it is possible to instead just run from therepository. However, you'll need to use slightly different commands. Add therepository to yourPYTHONPATH and invoke the tools as python modules, asillustrated below.

git clone https://github.com/cgmb/guardonce.gitexport PYTHONPATH="$(pwd)/guardonce"python -m guardonce.checkguard -r ~/myproject

git clone https://github.com/cgmb/guardonce.gitset "PYTHONPATH=%CD%\guardonce"python -m guardonce.checkguard -r ~/myproject

Note that on Windows you might need to invoke guardonce viapython -m even ifyou install with pip.