This is ubf-bertrpc, a framework for integrating UBF, EBF, and
Bert-RPC.  This repository depends on the ubf open source repository.


To download
===========

1. Get and install Git
   http://git-scm.com/

  and then append the following lines to your ~/.gitconfig file:

    [url "git://github.com/norton/gmt-bom.git"]
         insteadOf = git://github.com/norton/src/erl-tools/gmt-bom.git
    [url "git://github.com/norton/ubf.git"]
         insteadOf = git://github.com/norton/src/erl-tools/ubf.git
    [url "git://github.com/norton/ubf-bertrpc.git"]
         insteadOf = git://github.com/norton/src/erl-tools/ubf-bertrpc.git

  NOTE: UBF requires git version 1.7.x or newer.  UBF has been tested
  most recently with git version 1.7.1.1.

2. Download the 'bom.sh' tool and then download UBF

    $ mkdir -p ~/work/ubf-bertrpc
    $ cd ~/work/ubf-bertrpc
    $ git clone git://github.com/norton/bom.git .
    $ env BOM_GIT=git://github.com/norton/ \
      ./bom.sh co src/erl-tools/ubf-bertrpc

  NOTE: The Bill of Materials (BOM) system is a way to manage the
  builds of heterogeneous products with shared components using GIT,
  GIT-SVN, SVN, or CVS.  BOM maintains hierarchical dependencies
  between modules stored in a source code repository.  BOM is
  implemented using bash, make, and other UNIX tools.

  NOTE: The bom.sh commands 'diff' and 'status' can be used to check
  the differences and status of all components, respectively.  Type
  './bom.sh help' for further information.

  NOTE: The BOM system was originally developed by Gemini Mobile
  Technologies as an in-house tool to build and to package it's own
  commercial products.  BOM as been open-sourced as one of the helper
  tools for UBF.


To build - basic recipe
=======================

1. Get and install an erlang system
   http://www.erlang.org

   NOTE: UBF requires Erlang/OTP R13B01 or newer.  UBF has been tested
   most recently with Erlang/OTP R13B04.

2. Change to your working directory and create the top-level Makefile
   $ cd ~/work/ubf-bertrpc
   $ ./bom.sh make

3. Build UBF
   $ make ERL=/usr/local/hibari/ert/R13B04/bin/erl
     OR
   $ make ERL=/usr/local/hibari/ert/R13B04/bin/erl DEBUG="+debug_info"

   NOTE: Please specify the path to your erlang system's erl
   executable.

   NOTE: DEBUG="+debug_info" will produce DEBUG enabled beam files.

4. Run the unit tests
   $ make ERL=/usr/local/hibari/ert/R13B04/bin/erl test


To build - optional features
============================

A. Run unit test for one module.

   $ make ERL=/usr/local/hibari/ert/R13B04/bin/erl \
     DEBUG="+debug_info" \
     -C src/erl-tools/ubf-bertrpc__HEAD/src check

B. Clean one module

   $ make ERL=/usr/local/hibari/ert/R13B04/bin/erl \
     DEBUG="+debug_info" \
     -C src/erl-tools/ubf-bertrpc__HEAD/src clean

C. Rebuild one module

   $ make ERL=/usr/local/hibari/ert/R13B04/bin/erl \
     DEBUG="+debug_info" \
     -C src/erl-tools/ubf-bertrpc__HEAD/src

D. Generate EDocs for one module

   $ make ERL=/usr/local/hibari/ert/R13B04/bin/erl \
     DEBUG="+debug_info" \
     -C src/erl-tools/ubf-bertrpc__HEAD/src edoc

E. Run dialyzer for one module (and it dependencies)

   $ make ERL=/usr/local/hibari/ert/R13B04/bin/erl \
     DEBUG="+debug_info" \
     -C src/erl-tools/ubf-bertrpc__HEAD/src run-dialyzer

   NOTE: Dialyzer will not work unless all beam files have been
   compiled with debug information.


Documentation -- Where should I start?
======================================

This README is a good first step.  Check out and build using the "To
build" instructions above.

Eunit tests can be found in the Unit-EUnit-Files directory.  These
tests illustrate a generic module that uses UBF's contract manager for
checking Bert-RPC requests and responses.


What is UBF?
============

UBF is the "Universal Binary Format", designed and implemented by Joe
Armstrong.  UBF is a language for transporting and describing complex
data structures across a network.  It has three components:

   * UBF(A) is a "language neutral" data transport format, roughly
     equivalent to well-formed XML.

   * UBF(B) is a programming language for describing types in UBF(A)
     and protocols between clients and servers.  This layer is
     typically called the "protocol contract".  UBF(B) is roughly
     equivalent to Verified XML, XML-schemas, SOAP and WDSL.

   * UBF(C) is a meta-level protocol used between a UBF client and a
     UBF server.

See http://norton.github.com/ubf for further details.


What is Bert-RPC?
===============

Bert-RPC is a remote procedure call protocol.  See
http://bert-rpc.org/ for full details.

Bert-RPC is actually just a subset of UBF's binary network format
implementation known as "EBF".  The name "EBF" is short for "Erlang
Binary Format".


Credits
=======

Many, many thanks to Joe Armstrong, UBF's designer and original
implementor.

Gemini Mobile Technologies, Inc. has approved the release of this
repository under an MIT license.