Merge branch 'develop'

[submodule "protobuf-c"]

	path = vendor/protobuf-c

	url = https://github.com/atomicobject/protobuf-c

	branch = master

[submodule "kinetic-protocol"]

	path = vendor/kinetic-protocol

	url = https://github.com/Seagate/kinetic-protocol.git

[submodule "vendor/json-c"]

	path = vendor/json-c

	url = https://github.com/json-c/json-c

[submodule "vendor/protobuf-c"]

	path = vendor/protobuf-c

	url = https://github.com/protobuf-c/protobuf-c.git

	branch = master

    * Managed gems (installed w/ `bundle install`)

        * [rake](https://rubygems.org/gems/rake) Make-like build system

        * [ceedling](https://github.com/ThrowTheSwitch/Ceedling) Build system which extends rake to add support for interaction-based testing

            * [unity](https://github.com/ThrowTheSwitch/Unity) Unity C test framework (bundled w/ Ceedling)

            * [cmock](https://github.com/ThrowTheSwitch/CMock) CMock auto mock/fake module generator for C (bundle w/ Ceedling)

* [Valgrind](http://valgrind.org/) for validation of memory usage/management

* [Doxygen](https://github.com/doxygen)

    * [GraphViz](http://www.graphviz.org/) used by Doxygen for generating visualizations/graphs

    * The ByteArray and ByteBuffer types are used for exchanging variable length byte-arrays with kinetic-c

        * e.g. object keys, object value data, etc.

There are also some additional [architectural notes](docs) and time-sequence diagrams.

[docs]: https://github.com/Seagate/kinetic-c/blob/master/docs/sequence_diagrams/arch_docs.md

Common Developer Tasks

----------------------

* Build the library

    * `make`

* Start kinteic-java simulator(s)

    * `make [NUM_SIMS=N] start_sims # defaults to starting 2 simulators, if NUM_SIMS unspecified`

* Stop all running kinetic-java simulator(s)

    * `make stop_sims`

* Run all tests and build the library and examples

    * `make all`

* Run all unit/integration tests

    * `make test`

* Run all system tests

    * `make system_tests`

* Run a particular system test

    * make test_system_<module>

    * Will expect at least 2 simulators running by default (see above)

    * Uses the following environment vars, which are loaded dynamically at runtime

        * `KINTEIC_HOST[1|2]` - Configures the host name/IP for the specified device (default: `localhost`)

        * `KINTEIC_PORT[1|2]` - Configures the primary port for the specified device (default: `8124`, `8124`)

        * `KINTEIC_TLS_PORT[1|2]` - Configures the TLS port for the specified device (default: `8443`, `8444`)

* Apply license to source files (skips already licensed files)

    * `make apply_license`

Developer Tasks via Rake

------------------------

* Generate API documentation

* List rake tasks w/ descriptions

    * `rake -T`

* Test a single module (via Ceedling)

    * `rake test:<module_name>`

* Generate API documentation locally

    * `rake doxygen:gen`

* Generate and publish public API documentation

    * `rake doxygen:update_public_api`

* Build/install Google Protocol Buffers support for the Kinetic-Protocol

    * `rake proto`

Automated Tests

---------------

All test sources are located in `test/`, which are additionally broken up into:

    * `test/unit` - test suites for individual modules

    * `test/integration` - test suites which integrate multiple modules

    * `test/system` - system tests whick link against the kinetic-c release library

        * These tests require at least 2 simulator/drives to run against

Adding a new unit/integration test

----------------------------------

* Create a file named `test_<name>.c` in either `test/unit` or `test/integration`

    * These files will automatically be picked up by the Ceedling and added to the regression suite

    * Build targets for each module will be generated according to what header files are included in the test suite source.

        * e.g.

            * `#include "kinetic_session.h"` will link `kinetic_session.o` into the test target.

            * `#include "mock_kinetic_session.h"` will create a CMock mock of `kinetic_session.h` and link `mock_kinetic_session.o` into the test target.

            * `#include <some_lib.h>` will simply include the specified header, assuming it is already available in to the linker.

Adding a new system test

------------------------

* Create a file named `test_system_<name>.c` in `test/system`

    * This will create a new system test target invokable via: `make test_system_<name>`

    * System tests link/run against the full kinetic-c static library.

    * A generic test fixure is provided and linked into each system test from: `test/support/system_test_fixture.h/c`

        * See details above for runtime configuration of the system test kinetic devices for running remote simulators or kinetic device hardware.

Future development notes

------------------------

* epoll(2) could be used internally, in place of poll(2) and multiple

  listener threads. This only matters in a case where there is a large

  amount of idle listener connections. When there is a small number of

  file descriptors, it will add overhead, and epoll is only available

  on Linux.

* The listener can potentially leak memory on shutdown, in the case

  where responses have been partially received. This has been a low priority. 

* There is room for tuning the total number of messages-in-flight

  in the listener (controlled by `MAX_PENDING_MESSAGES`), how the

  backpressure is calculated (in `ListenerTask_GetBackpressure`), and the

  bit shift applied to the backpressure unit (the third argument to

  `bus_backpressure_delay`, e.g. `LISTENER_BACKPRESSURE_SHIFT`). These

  derive the feedback that pushes against actions that overload the

  system. The current setup has worked well with system/integration

  tests and a stress test program that attempts to overload the message

  bus over a loopback connection, but other workloads may have different

  performance trade-offs.

source "http://rubygems.org/"

gem 'bundler', '>= 1.3.5'

gem 'ceedling', '>= 0.16'

gem 'ceedling', '>= 0.18'

GEM

  remote: http://rubygems.org/

  specs:

    ceedling (0.16.0)

    ceedling (0.18.0)

      rake (>= 0.8.7)

      thor (>= 0.14.5)

    rake (10.4.2)

DEPENDENCIES

  bundler (>= 1.3.5)

  ceedling (>= 0.16)

  ceedling (>= 0.18)

	$(OUT_DIR)/kinetic_bus.o \

	$(OUT_DIR)/kinetic_auth.o \

	$(OUT_DIR)/kinetic_pdu_unpack.o \

	$(OUT_DIR)/kinetic_proto.o \

	$(OUT_DIR)/kinetic.pb-c.o \

	$(OUT_DIR)/kinetic_socket.o \

	$(OUT_DIR)/kinetic_message.o \

	$(OUT_DIR)/kinetic_logger.o \

	cd ${LIB_DIR}/bus && make clean

	if [ -f ${JSONC}/Makefile ]; then cd ${JSONC} && make clean; fi;

# Setup version info generation and corresponding dependencies

$(VERSION_INFO): $(VERSION_FILE)

	@ruby scripts/generate_version_info.rb

$(OUT_DIR)/kinetic_logger.o: $(VERSION_INFO)

$(OUT_DIR)/kinetic_client.o: $(VERSION_INFO)

config: makedirs update_git_submodules

	@echo Testing $(PROJECT)

	@echo --------------------------------------------------------------------------------

	bundle install

	bundle exec rake test_all

	bundle exec rake test:delta

JAVA_HOME ?= /usr

JAVA_BIN = $(JAVA_HOME)/bin/java

	$(RM) -f $(PREFIX)/include/kinetic_types.h

	$(RM) -f $(PREFIX)/include/kinetic_semaphore.h

	$(RM) -f $(PREFIX)/include/byte_array.h

	$(RM) -f $(PREFIX)/include/kinetic_proto.h

	$(RM) -f $(PREFIX)/include/kinetic.pb-c.h

	$(RM) -f $(PREFIX)/include/protobuf-c/protobuf-c.h

	$(RM) -f $(PREFIX)/include/protobuf-c.h

	if [ -f ${JSONC}/Makefile ]; then cd ${JSONC} && make uninstall; fi;