From 68dc14f80c7ae202ababbd0372a04b137ea8b563 Mon Sep 17 00:00:00 2001 From: Zetok Zalbavar Date: Sat, 20 Jun 2015 01:22:46 +0100 Subject: [PATCH] Add real instruction on how to use APIDSL and astyle also add to "tox{,.in}.h" note that "tox.h" shouldn't be edited directly, pointing to "tox.in.h" --- other/apidsl/README.md | 52 ++++++++++++++++++++++++++++++++++++------ other/apidsl/tox.in.h | 8 +++++++ other/astyle/README | 11 --------- other/astyle/README.md | 32 ++++++++++++++++++++++++++ toxcore/tox.h | 9 ++++++++ 5 files changed, 94 insertions(+), 18 deletions(-) delete mode 100644 other/astyle/README create mode 100644 other/astyle/README.md diff --git a/other/apidsl/README.md b/other/apidsl/README.md index 0b3e776d..c0f29ea4 100644 --- a/other/apidsl/README.md +++ b/other/apidsl/README.md @@ -1,11 +1,49 @@ -This folder contains the input file that can be used to generate the tox.h api -with: https://github.com/iphydf/apidsl +This folder contains the input file (``tox.in.h``) that has to be used to generate the ``tox.h`` api with: https://github.com/iphydf/apidsl -You can also use the following command if you can't install it: +# Minimal requirements -``` -curl -X POST --data-binary @- https://criticism.herokuapp.com/apidsl < tox.in.h > tox.h +There are some minimal requirements to contribute to ``tox.h``: +* unix enrironment +* ``astyle`` ``>=2.03`` +* [``apidsl``](https://github.com/iphydf/apidsl) (you can use provided service with curl instead) + +## Quick way + +If you want to do it quickly and you don't have time for anything other than copypasting commands, you should have ``curl`` installed. + + +1. Make sure that you have ``curl`` and ``>=astyle-2.03`` installed +2. Modify [``tox.in.h``](/other/apidsl/tox.in.h) +3. Run command below ↓ + +Command to run from ``toxcore`` directory (quick way, involves using curl): +```bash +rm toxcore/tox.h && \ +( curl -X POST --data-binary @- https://criticism.herokuapp.com/apidsl < ./other/apidsl/tox.in.h > ./toxcore/tox.h ) && \ +astyle --options=./other/astyle/astylerc ./toxcore/tox.h ``` -Note that the output must be passed through astyle with the config in -other/astyle/astylerc to generate the exact same file. +When formatting will be complete, you should see output like: +``` +Formatted ./toxcore/tox.h +``` + +You may want to make sure with ``git diff`` that changes made in ``tox.h`` reflect changes in ``tox.in.h``. + +And you're done. + + +## Manually + +If you prefer to have more control over what is happening, there are steps below: + +1. Install [``apidsl``](https://github.com/iphydf/apidsl) +2. Install ``astyle``, version 2.03 or later. +3. Modify [``tox.in.h``](/other/apidsl/tox.in.h) +4. Use ``apidsl`` ``??`` +5. Parse generated ``tox.h`` with astyle, minimal command for it would be: +```bash +astyle --options=./other/astyle/astylerc ./toxcore/tox.h +``` + +**Always pass output from ``apidsl`` through astyle.** \ No newline at end of file diff --git a/other/apidsl/tox.in.h b/other/apidsl/tox.in.h index 30c78e44..189fc43d 100644 --- a/other/apidsl/tox.in.h +++ b/other/apidsl/tox.in.h @@ -34,6 +34,14 @@ extern "C" { #endif %} + +/***************************************************************************** + * `tox.h` SHOULD *NOT* BE EDITED MANUALLY – any changes should be made to * + * `tox.in.h`, located in `other/apidsl/`. For instructions on how to * + * generate `tox.h` from `tox.in.h` please refer to `other/apidsl/README.md` * + *****************************************************************************/ + + /** \page core Public core API for Tox clients. * * Every function that can fail takes a function-specific error code pointer diff --git a/other/astyle/README b/other/astyle/README deleted file mode 100644 index 26802ec7..00000000 --- a/other/astyle/README +++ /dev/null @@ -1,11 +0,0 @@ -This directory can house various tools and utilities. - -astylerc - - This file can be used in the precommit hook to try its best - at making the code conform to the coding style document. - -pre-commit (*NIX only at the moment) - - Lints your file in adherence to the coding style doucment as - best as possible in terms of spacing, indenting, etc. - - Requires you to have astyle installed. - - To use, copy this file to ProjectTox-Core/.git/hooks diff --git a/other/astyle/README.md b/other/astyle/README.md new file mode 100644 index 00000000..f68edf68 --- /dev/null +++ b/other/astyle/README.md @@ -0,0 +1,32 @@ +This directory can house various tools and utilities. + +# How to use astyle + +## Manually + +### For all files + +Run from ``toxcore`` directory: +```bash +astyle --options=./other/astyle/astylerc ./toxcore/*.c ./toxcore/*.h ./toxdns/*.c ./toxdns/*.h ./testing/*.c ./toxav/*.c ./toxav/*.h ./other/*.c ./other/bootstrap_daemon/*.c ./toxencryptsave/*.c ./toxencryptsave/*.h ./auto_tests/*.c +``` + +### For selected file + +Run from ``toxcore`` directory, e.g. for [``tox.h``](/toxcore/tox.h) file: +```bash +astyle --options=./other/astyle/astylerc ./toxcore/tox.h +``` + + +## Automatically, as pre-commit hook (*NIX only) + +Copy [``astylerc``](/other/astyle/astylerc) to ``toxcore/.git/hooks`` + + + +# Why + +``astylerc`` - this file can be used in the pre-commit hook to try its best at making the code conform to the coding style of toxcore. + +Furthermore, it is being used to format ``tox.h`` after using [``apidsl``](/other/apidsl) to generate it. \ No newline at end of file diff --git a/toxcore/tox.h b/toxcore/tox.h index 14c9f616..fd0792f2 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -32,6 +32,15 @@ extern "C" { #endif + +/******************************************************************************* + * `tox.h` SHOULD *NOT* BE EDITED MANUALLY – any changes should be made to * + * `tox.in.h`, located in `other/apidsl/`. For instructions on how to * + * generate `tox.h` from `tox.in.h` please refer to `other/apidsl/README.md` * + ******************************************************************************/ + + + /** \page core Public core API for Tox clients. * * Every function that can fail takes a function-specific error code pointer