diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..85b7c4f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,78 @@ +# Working on Better Enums + +All contributions are welcome — feedback, documentation review, and, of +course, pull requests, or patch suggestions. A list of contributors is +maintained in the CONTRIBUTORS file. I am grateful to everyone mentioned. + +## Working on code + +The development environment is in a fairly embryonic state. For example, the +automatic test suite isn't that easy to set up to work with VC++. If you want to +develop with VC++, *please* send me an email at +[antonbachin@yahoo.com](mailto:antonbachin@yahoo.com) and I will get on +improving it speedily. For now, the easiest way to develop on Windows is to +install GCC or clang from [Cygwin][cygwin]. + +If your change includes code, you will want to test it. Here is how to do this. +Basic testing is currently only supported in a reasonable automated fashion on +GCC-like C++11 compilers, i.e. GCC and clang. First, you will need: + + - A C++ compiler, + - Python 2.7, + - Make, and + - [CxxTest][cxxtest]. + +If you also want to edit the documentation and re-generate the examples from the +tutorial Markdown, you will need the [mistune][mistune] library for Python. + +Clone the repository and make your changes against `master`. To test, go to the +`test/` directory and run `./test.py`. This script assumes that your GCC-like +system compiler is symlinked as `c++` (generally true) and accepts `-std=c++11`. +The script will build and run the unit test, compare the example programs' +output against expected output, and do a test that links two translation units +that declare the same enum. If the exit status is zero, your change probably +didn't break anything. + +The reason I say *probably* is because the change actually needs to be tested on +a large number of compilers and in various configurations, but I can't expect +you to do that. Go ahead and submit your GitHub pull request, and I will do the +testing myself and let you know if there are any problems, and probably how to +fix them. If you don't want to go through the tedium of fixing them without +being able to test yourself, then I hope you will allow me to take your patch, +apply whatever changes are needed to get it to pass on all compilers, and then +apply it to `master` and give you credit with `git commit --author`. I will let +you know exactly what I'm doing to your code before I apply it, and you can, of +course, request further changes or refuse. + +--- + +If you want to run only the samples, go to `example/` and run `make`. This makes +the same assumptions by default: your system compiler is `c++` and it accepts +`-std=c++11`. + +--- + +The rest of this file describes the testing process I will do, in case you want +to try it yourself. + +If you run `./test.py --all` on a Unix-like system, the script will assume that +you have symlinks `clang33` to `clang36` and `gcc43` to `gcc51`. It will run the +same tests as mentioned above, but on every one of those compilers. + +Similarly, if you run `./test.py --all` on a Windows system, it will assume that +you have binaries `vc2013` and `vc2015`. These are actually scripts on my +development machine that pass the right options to the different verisons of +`cl.exe`. It's pretty crufty at this point. + +--- + +The reason I am not working on improving this immediately is because I am +looking into using some kind of third-party service. I really don't expect +anyone to install multiple GCC-like and Microsoft compilers to work on the code. +It would be nice if code changes could be submitted over the network by some +script and tested on a remote machine, or machines, that have all of this +installed and configured. + +[cygwin]: https://www.cygwin.com +[cxxtest]: http://cxxtest.com +[mistune]: https://github.com/lepture/mistune diff --git a/CONTRIBUTORS b/CONTRIBUTORS new file mode 100644 index 0000000..739143c --- /dev/null +++ b/CONTRIBUTORS @@ -0,0 +1,10 @@ +Here you will find a list of everyone I have to thank for contributing code, +suggestions, comments, other feedback, or anything else that was useful to the +library. This file never shrinks - if a name goes missing, it's because a chat +handle was replaced by a real name. There is no significance to the order. + +Thanks to: + +Gottlob Frege +Ben Alex +SlashLife (freenode) diff --git a/README.md b/README.md index 8b2d619..ef8a795 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Reflective compile-time C++ enum library with clean syntax, in a single header file. For example: #include - ENUM(Channel, int, Red = 1, Green, Blue) + ENUM(Channel, uint8_t, Red = 1, Green, Blue) defines a type `Channel`. You can then do natural things such as: @@ -43,11 +43,13 @@ The interface is the same for C++98 — you just have to use most of it at run time only. This library does provide scoped and sized enums, something not built into C++98. -See the [project page][project] for full documentation. +See the [project page][project] for full documentation and [here][tutorial] for +a simple working program. -[max]: http://aantron.github.io/better-enums/demo/BitSets.html -[enforce]: http://aantron.github.io/better-enums/demo/SpecialValues.html -[project]: http://aantron.github.io/better-enums +[max]: http://aantron.github.io/better-enums/demo/BitSets.html +[enforce]: http://aantron.github.io/better-enums/demo/SpecialValues.html +[project]: http://aantron.github.io/better-enums +[tutorial]: http://aantron.github.io/better-enums/tutorial/HelloWorld.html ## Installation diff --git a/test/Makefile b/test/Makefile index 9e6cd57..b94190c 100644 --- a/test/Makefile +++ b/test/Makefile @@ -1,13 +1,15 @@ .PHONY : default default : - make -C ../doc examples python test.py .PHONY : platform -platform : - make -C ../doc examples +platform : examples python test.py --all +.PHONY : examples +examples : + make -C ../doc examples + .PHONY : clean clean : rm -rf platform *.obj