diff --git a/.gitignore b/.gitignore --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,6 @@ # Tests tests/test + +# Documentation +doc/build/ diff --git a/Doxyfile b/Doxyfile new file mode 100644 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,35 @@ +# ------------------------------------------------------------- +# Doxyfile :: configuration for Doxygen documentation system +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# Version: Doxyfile 1.9.6 +# Project: Nasqueron +# License: Trivial work, not eligible to copyright +# ------------------------------------------------------------- + +# ------------------------------------------------------------- +# Project +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +PROJECT_NAME = "RabbitMQ TCL" +PROJECT_NUMBER = 0.1.1 +PROJECT_BRIEF = "AMQP client TCL extension" +PROJECT_LOGO = doc/logo-nasqueron.png + +OUTPUT_DIRECTORY = doc/build +STRIP_FROM_PATH = src/ +OPTIMIZE_OUTPUT_FOR_C = YES + +NUM_PROC_THREADS = 0 + +# ------------------------------------------------------------- +# Build +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_PRIV_VIRTUAL = YES + +INPUT = src \ + doc/INDEX.md + +USE_MDFILE_AS_MAINPAGE = doc/INDEX.md diff --git a/Makefile b/Makefile new file mode 100644 --- /dev/null +++ b/Makefile @@ -0,0 +1,71 @@ +# ------------------------------------------------------------- +# +# ___ __ \_____ ___ /____ /____(_)_ /___ |/ /_ __ \ +# __ /_/ / __ `/_ __ \_ __ \_ /_ __/_ /|_/ /_ / / / +# _ _, _// /_/ /_ /_/ / /_/ / / / /_ _ / / / / /_/ / +# /_/ |_| \__,_/ /_.___//_.___//_/ \__/ /_/ /_/ \___\_\ +# _____________________ +# RabbitMQ C AMQP client library TCL wrapper ___ __/_ ____/__ / +# TCL module to connect to AMQP brokers. __ / _ / __ / +# _ / / /___ _ /___ +# /_/ \____/ /_____/ +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# Project: Nasqueron +# Description: Build instructions for make +# License: BSD-2-Clause +# Note: This Makefile is compatible with BSD make. +# The src/Makefile currently requires GNU make. +# ------------------------------------------------------------- + +BUILD=build/ + +DOXYGEN=doxygen +GNU_MAKE=gmake +MAKE=${GNU_MAKE} +RMDIR=rm -rf + +# ------------------------------------------------------------- +# Main targets +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +all: build doc + +build: build-lib build-pkg + +clean: clean-build clean-doc + +# ------------------------------------------------------------- +# Build targets +# +# The src/ Makefile provides two parts of the build: +# - lib: the TCL extension module +# - pkg: to allow to use `package require` instead of `load` +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +build-lib: ${BUILD}/rabbitmq.so +build-pkg: ${BUILD}/pkgIndex.tcl + +${BUILD}/rabbitmq.so: + (cd src && $(MAKE) lib) + +${BUILD}/pkgIndex.tcl: + (cd src && $(MAKE) pkg) + +# ------------------------------------------------------------- +# Documentation targets +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +doc: doc/build/html/index.html + +doc/build/html/index.html: + ${DOXYGEN} + +# ------------------------------------------------------------- +# Clean targets +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +clean-doc: + ${RMDIR} doc/build + +clean-build: + (cd src && ${MAKE) clean) diff --git a/doc/INDEX.md b/doc/INDEX.md new file mode 100644 --- /dev/null +++ b/doc/INDEX.md @@ -0,0 +1,73 @@ +# RabbitMQ TCL + +This library is a wrapper around [rabbitmq-c](https://github.com/alanxz/rabbitmq-c). + +It exposes the C functions allowing to interact with a RabbitMQ server in TCL. + +## Documentation + +* rabbitmq-tcl.c - the extension code +* makePkgIndex.c - a tool to prepare pkgIndex.tcl + +## Customize the build + +### config.h + +If you want to be able to use different default values, you can edit the defines +at `src/config.h`, then rebuild the extension. + +### E4C + +This extension is a wrapper around librabbitmq, which is not bulletproof against +null pointer errors. + +In a critical context, we suggest to enable e4c. If a command `mq quux` would +try to use a NULL pointer, instead of segfault, you would get a TCL error, +and then would be able to resume operations: + +``` +% mq quux +Segmentation violation. +% +``` + +## Licensing + +(c) 2015, Nasqueron, some rights reserved. +Released under BSD-2-Clause license. + +This work includes the exceptions4c library. +(c) 2013 Guillermo Calvo +Released under LGPL license. + +### Note if you relicense a derivative work + +If you create any derivative work of this library, you must do one of the +following actions: + + * drop exceptions4c support (rm vendor/e4c and the #ifdef USE_E4C blocks) + * release the whole work under LGPLv3 or GPLv3 + * publish source code or object form (.o) so it's possible to relink + against another version of exceptions4c [this is what we do] + +According http://www.gnu.org/licenses/gpl-faq.html#LGPLStaticVsDynamic, you can +link staticly against a LGPL library as long as you provide the .o object of +your application stripped of the LGPL code or provide the source code and build +tools to achieve it. + +## Misc + +### Acknowledgment + +* Alan Antonuk, rabbitmq-c maintainer +* Fastbase, which provides [fbsql](http://www.fastbase.co.nz/fbsql/fbsql.c), + which is used as the model and starting point for this library. + +### Colophon + +This work has been created for Nasqueron, to allow their operations and +infrastructure TCL code to interact to our message broker. + +**Editors used:** vim, Cloud9 +**Tools used:** Arcanist, clang-format +**Compiler:** clang/llvm diff --git a/doc/logo-nasqueron.png b/doc/logo-nasqueron.png new file mode 100644 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 GIT binary patch literal 0 Hc$@<O00001 literal 0 Hc$@<O00001