| 820 | | This is seriously cool, but TODO awaiting me writing it up. |
| | 820 | In the past year, many of the online C++ compiler websites have made available a REST API with which you can upload a ready to play sandbox of your C++ library with an example of usage. One which stands out is http://melpon.org/wandbox as it provides bleeding edge trunk C++ compilers as well as latest Boost, lets you upload multiple files which most of the other services do not, plus it lets you ask for a permalink to an uploaded sandbox which makes it particularly amenable for integration into your Continuous Integration setup (i.e. push a copy of the library + playpen per commit and incorporate the permalink into your generated docs). |
| | 821 | |
| | 822 | To that end the Boost community have been busy developing tooling to automate wandbox from Travis etc, and I have taken some of that tooling and bent it to my own ends. Firstly, take a look at https://github.com/BoostGSoC13/boost.afio/blob/master/send_to_wandbox.sh: |
| | 823 | |
| | 824 | {{{ |
| | 825 | #!/bin/bash |
| | 826 | rm -rf send_to_wandbox_tmp |
| | 827 | mkdir send_to_wandbox_tmp |
| | 828 | include/boost/afio/bindlib/scripts/GenSingleHeader.py -DAFIO_STANDALONE=1 -DSPINLOCK_STANDALONE=1 -DBOOST_AFIO_DISABLE_VALGRIND=1 -Eafio_iocp.ipp -Ent_kernel_stuff -Evalgrind include/boost/afio/afio.hpp > include/boost/afio/single_include.hpp |
| | 829 | sed "1s/.*/#include \"afio_single_include.hpp\"/" example/readwrite_example.cpp > send_to_wandbox.cpp |
| | 830 | gcc -fpreprocessed -dD -E -P include/boost/afio/single_include.hpp > send_to_wandbox_tmp/afio_single_include2.hpp 2>/dev/null |
| | 831 | sed "/^$/d" send_to_wandbox_tmp/afio_single_include2.hpp > send_to_wandbox_tmp/afio_single_include.hpp |
| | 832 | rm -rf send_to_wandbox_tmp/afio_single_include2.hpp |
| | 833 | #include/boost/afio/bindlib/scripts/send_to_wandbox.py send_to_wandbox_tmp send_to_wandbox.cpp |
| | 834 | URL=`include/boost/afio/bindlib/scripts/send_to_wandbox.py send_to_wandbox_tmp send_to_wandbox.cpp | sed -e 's/.*\(http:\/\/[^ '"'"']*\).*/\1/'` |
| | 835 | if [[ $FRAME != "" ]]; then |
| | 836 | echo '<iframe src="'$URL'" frameborder="0" style="height: 100%; width: 100%;" height="100%" width="100%"></iframe>' |
| | 837 | else |
| | 838 | echo $URL |
| | 839 | fi |
| | 840 | }}} |
| | 841 | |
| | 842 | This shell script invokes the `GenSingleHeader.py` script in APIBind (https://github.com/ned14/Boost.APIBind/blob/master/scripts/GenSingleHeader.py) which will take a set of include files and follow any `#include`s to generate a single very large include file. It takes command arguments: |
| | 843 | |
| | 844 | `-Iincludepath`:: Any paths to search for includes. |
| | 845 | `-Dmacro`:: Any macros to hardcode at the beginning of the output. Note that macro logic is NOT followed by this script. |
| | 846 | `-Aalwaysinclude`:: Always include an include file even if previously included. Substring matched. |
| | 847 | `-Ealwaysexclude`:: Always exclude an include file no matter what. Substring matched. |
| | 848 | |
| | 849 | Unless you have very messy headers where logic controlled precise include order matters, this script is pretty good at generating a unified header file which works, though it may require a bit of fiddling with defines to get the output to work without a build system in place. After `GenSingleHeader.py` has worked, we ask GCC's preprocessor to eliminate any comments for us, then we use sed to eliminate any blank lines. Finally we invoke the `send_to_wandbox.py` script in APIBind (https://github.com/ned14/Boost.APIBind/blob/master/scripts/send_to_wandbox.py) to push the contents of the send_to_wandbox_tmp directory and the example file we want the user to play with, extract the permalink url sent back to use and echo that out for any CI scripts calling this script. In AFIO's case, that then appears as a giant "Try AFIO now in online web compiler" blue button at http://boostgsoc13.github.io/boost.afio/. |
| | 850 | |
| | 851 | Other examples of single mouse click C++ library tryout: |
| | 852 | |
| | 853 | * https://github.com/ldionne/hana/blob/develop (the "try it online" badge). |
| | 854 | * https://github.com/krzysztof-jusiak/di (the "try boost.di online" badge). |
| | 855 | |
| | 856 | Something I haven't seen yet, but would be taking a page from Rust, is that every documentation example code could be launched on demand in wandbox so people could play with the code. |
