README file, OS X build support

Added top-level README.md with details of building, links to info
Added OS X build rule to Makefile. NB needs updating for samples
Added Paho logo to doc dir for potential future use.

README.md

+# Eclipse Paho MQTT C client
+
+
+This repository contains the source code for the [Eclipse Paho](http://eclipse.org/paho) MQTT C client library. 
+
+This code builds libraries which enable applications to connect to an [MQTT](http://mqtt.org) broker to publish messages, and to subscribe to topics and receive published messages.
+
+Both synchronous and asynchronous modes of operation are supported.
+
+## Build requirements / compilation
+
+The build process requires GNU Make and gcc, and also requires OpenSSL libraries and includes to be available. There are make rules for a number of Linux "flavors" including ARM and s390, OS X, AIX and Solaris.
+
+The documentation requires doxygen and optionally graphviz. 
+
+Before compiling, set some environment variables (or pass these values to the make command directly) in order to configure library locations and other options.
+
+Specify the location of OpenSSL using `SSL_DIR`
+
+e.g. using [homebrew](http://mxcl.github.com/homebrew/) on OS X:
+
+`export SSL_DIR=/usr/local/Cellar/openssl/1.0.1e`
+
+Specify where the source files are in relation to where the make command is being executed.
+
+``export MQTTCLIENT_DIR=../src``
+
+To build the samples, enable the option (`BUILD_SAMPLES`), and specify the location of the code:
+
+```
+export BUILD_SAMPLES=YES
+export SAMPLES_DIR=../src/samples
+```
+
+One more useful environment variable is ``TARGET_PLATFORM``. This provides for cross-compilation. Currently the only recognised value is "Arm" - for instance to cross-compile a Linux ARM version of the libraries:
+
+``export TARGET_PLATFORM=Arm``
+
+## Libraries
+
+The Paho C client comprises four shared libraries:
+
+ * libmqttv3a.so - asynchronous
+ * libmqttv3as.so - asynchronous with SSL
+ * libmqttv3c.so - "classic" / synchronous
+ * libmqttv3cs.so - "classic" / synchronous with SSL
+
+## Usage and API
+
+Detailed API documentation is available by building the Doxygen docs in the  ``doc`` directory. A [snapshot is also available online](http://www.eclipse.org/paho/files/mqttdoc/Cclient/index.html).
+
+## Runtime tracing
+
+A number of environment variables control runtime tracing of the C library. 
+
+Tracing is switched on using ``MQTT_C_CLIENT_TRACE`` (a value of ON traces to stdout, any other value should specify a file to trace to). 
+
+The verbosity of the output is controlled using the  ``MQTT_C_CLIENT_TRACE_LEVEL`` environment variable - valid values are ERROR, PROTOCOL, MINIMUM, MEDIUM and MAXIMUM (from least to most verbose).
+
+The variable ``MQTT_C_CLIENT_TRACE_MAX_LINES`` limits the number of lines of trace that are output.
+
+```
+export MQTT_C_CLIENT_TRACE=ON
+export MQTT_C_CLIENT_TRACE_LEVEL=PROTOCOL
+```
+
+## Reporting bugs
+
+Please report bugs under the "MQTT" Component in [Eclipse Bugzilla](http://bugs.eclipse.org/bugs) for the Paho Technology project.
+
+## More information
+
+Discussion of the Paho clients takes place on the [Eclipse paho-dev mailing list](https://dev.eclipse.org/mailman/listinfo/paho-dev).
+
+General questions about the MQTT protocol are discussed in the [MQTT Google Group](https://groups.google.com/forum/?hl=en-US&fromgroups#!forum/mqtt).
+
+There is much more information available via the [MQTT community site](http://mqtt.org).

build/Makefile

 # Build output is produced in the current directory.
+
 # MQTTCLIENT_DIR must point to the base directory containing the MQTT client source code.
 # Example:  make -f makefile MQTTCLIENT_DIR=V3Client/MQTTClient
+
 # Note: this makefile requires gnu make which you may need to obtain if compiling on AIX or Solaris
+# Note: on OS X you should install XCode and the associated command-line tools
+
 ifndef MQTTCLIENT_DIR
   MQTTCLIENT_DIR = $(CURDIR)
 endif
@@ -254,6 +258,59 @@ endif
 
 endif
 
+ifeq ($(OSTYPE),Darwin)
+
+ifeq ($(MACHINETYPE),x86_64)
+	CC = gcc
+
+	CCFLAGS_SO = -fPIC -Os -Wall -I ${SSL_DIR}/include
+	CCFLAGS_EXE = -I ${MQTTCLIENT_DIR}
+	LDFLAGS = -shared -Wl,-install_name,lib${MQTTLIB}.so
+	LDFLAGS_S = -shared -Wl,-install_name,lib${MQTTLIB_S}.so -ldl -Wl,-all_load -L${SSL_DIR}/lib -lcrypto -lssl
+	LDFLAGS_A = -shared -Wl,-install_name,lib${MQTTLIB_A}.so
+	LDFLAGS_AS = -shared -Wl,-install_name,lib${MQTTLIB_AS}.so -ldl -Wl,-all_load -L${SSL_DIR}/lib -lcrypto -lssl
+	LDFLAGS_EXE = -lpthread
+
+	MQTTLIB_IA64 = darwin_ia64/lib${MQTTLIB}.so
+	MQTTLIB_IA64_S = darwin_ia64/lib${MQTTLIB_S}.so
+	MQTTLIB_IA64_A = darwin_ia64/lib${MQTTLIB_A}.so
+	MQTTLIB_IA64_AS = darwin_ia64/lib${MQTTLIB_AS}.so
+
+ifdef BUILD_SAMPLES
+all: darwin_ia64 ${MQTTLIB_IA64} ${MQTTLIB_IA64_A} ${MQTTLIB_IA64_S} ${MQTTLIB_IA64_AS} samples
+else
+all: darwin_ia64 ${MQTTLIB_IA64} ${MQTTLIB_IA64_A} ${MQTTLIB_IA64_S} ${MQTTLIB_IA64_AS}
+endif
+
+darwin_ia64:
+	-mkdir darwin_ia64
+
+samples:
+	-mkdir ${SAMPLES_DIR}/darwin_ia64
+	${CC} -m64 -I ${MQTTCLIENT_DIR} -L ${MQTTCLIENT_DIR}/darwin_ia64 -o ${SAMPLES_DIR}/darwin_ia64/MQTTV3Sample ${SAMPLES_DIR}/MQTTV3Sample.c -lmqttv3c -lpthread
+	${CC} -m64 -I ${MQTTCLIENT_DIR} -L ${MQTTCLIENT_DIR}/darwin_ia64 -o ${SAMPLES_DIR}/darwin_ia64/MQTTV3SSample ${SAMPLES_DIR}/MQTTV3SSample.c -lmqttv3cs -lpthread
+	${CC} -m64 -I ${MQTTCLIENT_DIR} -L ${MQTTCLIENT_DIR}/darwin_ia64 -o ${SAMPLES_DIR}/darwin_ia64/MQTTV3ASample ${SAMPLES_DIR}/MQTTV3ASample.c -lmqttv3a -lpthread
+	${CC} -m64 -I ${MQTTCLIENT_DIR} -L ${MQTTCLIENT_DIR}/darwin_ia64 -o ${SAMPLES_DIR}/darwin_ia64/MQTTV3ASSample ${SAMPLES_DIR}/MQTTV3ASSample.c -lmqttv3as -lpthread
+
+${MQTTLIB_IA64}: ${SOURCE_FILES} ${HEADERS}
+	${CC} -m64 ${CCFLAGS_SO} ${LDFLAGS} -o $@ ${SOURCE_FILES}
+	strip -x $@
+
+${MQTTLIB_IA64_S}: ${SOURCE_FILES_S} ${HEADERS}
+	${CC} -m64 ${CCFLAGS_SO} ${LDFLAGS_S} -o $@ ${SOURCE_FILES_S} -DOPENSSL
+	strip -x $@
+
+${MQTTLIB_IA64_A}: ${SOURCE_FILES_A} ${HEADERS_A}
+	${CC} -m64 ${CCFLAGS_SO} ${LDFLAGS_A} -o $@ ${SOURCE_FILES_A}
+	strip -x $@
+
+${MQTTLIB_IA64_AS}: ${SOURCE_FILES_AS} ${HEADERS_A}
+	${CC} -m64 ${CCFLAGS_SO} ${LDFLAGS_AS} -o $@ ${SOURCE_FILES_AS} -DOPENSSL
+	strip -x $@
+
+endif
+
+endif
 
 ifeq ($(OSTYPE),AIX)
 # applications must be linked with -I. -L. -lmqttv3c -Wl,-brtl -pthread