107 lines
3.5 KiB
ReStructuredText
107 lines
3.5 KiB
ReStructuredText
======
|
|
astyle
|
|
======
|
|
|
|
This is a modified version of astyle: http://astyle.sourceforge.net
|
|
|
|
Our intention is to patch astyle to follow the Steinwurf coding style
|
|
as closely as possible: http://docs.steinwurf.com/coding_style.html
|
|
|
|
The Steinwurf codebase contains some heavily-templated C++11 code that can be
|
|
a true challenge for a code formatting tool. A comprehensive example
|
|
for this coding style is located here:
|
|
https://github.com/steinwurf/astyle/blob/master/test/correct_style.cpp
|
|
|
|
Quick start
|
|
-----------
|
|
|
|
If you already installed a C++11 compiler, git and python on your system,
|
|
then you can clone this repository to a suitable folder::
|
|
|
|
git clone git@github.com:steinwurf/astyle.git
|
|
|
|
Configure and build the project (use the ``cxx_default`` mkspec, because
|
|
fabric will look for the ``astyle`` binary at this default location)::
|
|
|
|
cd astyle
|
|
python waf configure --cxx_mkspec=cxx_default
|
|
python waf build
|
|
|
|
Running astyle manually
|
|
-----------------------
|
|
|
|
First of all, you should copy the ``.astylerc`` options file to your home
|
|
folder.
|
|
|
|
On Unix systems::
|
|
|
|
cp .astylerc ~
|
|
|
|
On Windows::
|
|
|
|
copy .astylerc %USERPROFILE%\astylerc
|
|
|
|
After this, you can call ``astyle`` to format a single file (be careful,
|
|
because **it will not make a backup** for the original file)::
|
|
|
|
build/cxx_default/astyle test.cpp --print-changes
|
|
|
|
The ``--print-changes`` option prints out every line that is changed
|
|
during the formatting. This is especially useful with the ``--dry-run``
|
|
option that will not write any modifications to the file::
|
|
|
|
build/cxx_default/astyle test.cpp --print-changes --dry-run
|
|
|
|
**Warning**: Be careful about the working directory if you invoke the
|
|
following command, because you can accidentally format a lot of files!
|
|
|
|
You can format all C/C++ source files within the current directory with the
|
|
recursive search (``-R``) option::
|
|
|
|
cd my-project
|
|
path/to/astyle -Q -R *.cpp *.hpp *.c *.h --print-changes
|
|
|
|
With the ``-Q`` option, astyle will only display information about the
|
|
formatted files (it will not list the unchanged files).
|
|
|
|
Instead of copying ``.astylerc`` to your home folder, you can also specify
|
|
the options file directly. The file can change in the future, so this is the
|
|
recommended solution if you want to invoke astyle from your IDE::
|
|
|
|
cd my-project
|
|
path/to/astyle --options=/path/to/.astylerc -Q -R *.cpp *.hpp *.c *.h --print-changes
|
|
|
|
Running astyle with fabric (for Steinwurf projects)
|
|
---------------------------------------------------
|
|
|
|
For convenience, we also have fabric tasks to run astyle on Steinwurf projects.
|
|
|
|
The ``astyle.format_code`` task will format all C/C++ source files in the
|
|
selected project::
|
|
|
|
fab astyle.format_code:my-project
|
|
|
|
You can also add ``update_astyle=True`` to automatically update the astyle
|
|
project and build the latest binary::
|
|
|
|
fab astyle.format_code:my-project,update_astyle=True
|
|
|
|
The ``astyle.check_code`` task will not make any changes in the C/C++ source
|
|
files, it will only print the required changes in the selected project::
|
|
|
|
fab astyle.check_code:my-project
|
|
|
|
Integrating astyle with the Atom text editor
|
|
--------------------------------------------
|
|
|
|
After building astyle, please install the following packages in Atom::
|
|
|
|
apm install formatter
|
|
apm install formatter-astyle
|
|
|
|
In the settings for ``formatter-astyle``, point to the astyle binary in
|
|
``build/cxx_default`` and to the ``.astylerc`` file in the root of this
|
|
repository.
|
|
|
|
The keyboard shortcuts can be found in the settings for the formatter package.
|