forked from chinnurtb/erlang-amqp-client
/
README
181 lines (130 loc) · 6.13 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
AMQP client for Erlang
======================
This code implements a client for AMQP in the Erlang programming
language.
This client offers both a networked version that uses standard
TCP-based AMQP framing and a direct client that uses native Erlang
message passing to a RabbitMQ broker.
The API exposed to the user is common to both clients, so each version
can be used interchangeably without having to modify any client code.
The TCP networked client has been tested with RabbitMQ server 1.4.0,
but should theoretically work with any 0-8 compliant AMQP server.
The direct client is bound to an 0-8 compliant broker using native
Erlang message passing, which in the absence of an alternative Erlang
AMQP implementation means that it only works with RabbitMQ.
It does however provide a level of abstraction above the internal
server API of RabbitMQ, meaning that you can write client code in
Erlang and still remain isolated from any API changes in the
underlying broker.
It also provides a client-orientated API into RabbitMQ, allowing the
user to reuse AMQP knowledge gained by using AMQP clients in other
languages.
The advantage of the direct client is that it eliminates the network
overhead as well as the marshaling to and from the AMQP wire format,
so that neither side has to decode or encode any AMQP frames.
Prerequisites
-------------
In order to compile/run this code you must have the following
installed:
- Erlang/OTP, R11B-5 or later, http://www.erlang.org/download.html
- The RabbitMQ server, 93cc2ca0ba62 or later
- Eunit, the Erlang unit testing framework - currently the whole build process
depends on eunit because all of the modules are compiled together.
A future version of the build process could remove this dependency when you
only want to compile the core libraries.
Getting Eunit
-------------
The test suite uses eunit which is either available bundled with OTP from
release R12B-5 onwards or as a separate download that you will need to build
yourself if you are using an older version of Erlang.
* If you are using R12B-5 or newer:
Just skip to the next section.
* If you are using R12B-4 or older:
Check out eunit from their Subversion repository and build it:
$ svn co http://svn.process-one.net/contribs/trunk/eunit eunit
$ cd eunit
$ make
After this has sucessfully been built, you will need to create a symlink to
the eunit directory in your OTP installation directory:
$ cd $OTP_HOME/lib/erlang/lib
$ ln -sf PATH_TO_EUNIT eunit
where $OTP_HOME is the location of your Erlang/OTP installation.
Compiling the Erlang client
-------------------------
You will need to get a copy of the server in order to be able to use it's
header files and runtime libraries. A good place to put this is in the sibling
directory to the Erlang client (i.e: ../rabbitmq-server), which is the default
that the Makefile expects. In this case, you can just run make:
$ make
If the source tree for the server is not in the sibling directory, you will
need to specify the path to this directory:
$ make BROKER_DIR=/path/to/server
In this case, make sure you specify BROKER_DIR every time you run a make target.
Running the network client, direct client and packaging tests
-------------------------------------------------------------
The direct client has to be run in the same Erlang VM instance as the
RabbitMQ server. In order to use the makefile to run tests, you will need to
shutdown any other running instance of RabbitMQ server that you may have on
your machine. This is because the Makefile test targets boot their own instance
of RabbitMQ with settings depending on the test.
To run these tests, use either of the following targets:
$ make test_network
$ make test_direct
$ make test_common_package
Or to run all tests:
$ make all_tests
If any test fails, the make command will return a non-zero exit code. The reason
is logged by the server in /tmp/rabbit-sasl.log by default.
The network client test can also be run from a separate Erlang VM instance from
RabbitMQ server. You can *start an instance of the server* and then, in the
rabbitmq-erlang-client folder, type
rabbitmq-erlang-client $ make compile_tests
rabbitmq-erlang-client $ make run
erl -pa ebin ../rabbitmq-server/ebin tests
Erlang (BEAM) emulator version 5.6.5 [source] [64-bit] [smp:4] \
[async-threads:0] [hipe] [kernel-poll:false]
Eshell V5.6.5 (abort with ^G)
1> network_client_SUITE:test().
To get more examples of the API, look at the functions in the test_util module.
Make targets
------------
Interesting rabbitmq-erlang-client make targets include
all
The default target. Builds the client (does not compile the tests).
compile
Builds the client.
compile_tests
Builds the client test modules.
run
Builds the client and starts an Erlang shell with both the client and the
server in the load path.
run_in_broker
Builds the client and starts RabbitMQ server with shell and the client
included in load path.
clean
Removes build products and wipes all files produced by any other
rabbitmq-erlang-client make targets or client errors.
dialyze
Analyses the client source code with dialyzer. Uses PLT file from default
location: ~/.dialyzer_plt. Use
$ make PLT=/path/to/plt dialyze
to override this. Add broker to PLT beforehand, otherwise you will a lot
of 'unknown function' warnings. See add_broker_to_plt make target.
dialyze_all
Same as dialyze, except that this also analyses tests source code.
add_broker_to_plt
Adds broker .beam files to default plt. Use
$ make PLT=/path/to/plt add_broker_to_plt
to override default plt location ( ~/.dialyzer_plt ).
source_tarball
Creates tarball of all the client source code.
package
Creates an erlang archive of the client.
common_package
Creates an erlang archive of the server modules required by the erlang
client.
all_tests
Clean compiles the client and client tests source code and runs
network_client_SUITE, direct_client_SUITE and packaging tests. During the
testing, this make target runs an instance of the broker, so make sure
there is no other instance of RabbitMQ server running.