README
1Welcome
2=======
3
4Crossroads I/O ("libxs") is a library for building scalable and high
5performance distributed applications. It fits between classic BSD sockets,
6JMS/AMQP-style message queues, and enterprise message-oriented middleware.
7
8Crossroads I/O extends the standard socket interfaces with features
9traditionally provided by specialised messaging middleware products,
10providing an abstraction of asynchronous message queues, multiple messaging
11patterns, message filtering (subscriptions), seamless access to multiple
12transport protocols, and more.
13
14Crossroads I/O provides a native C API for applications. Support for many
15more languages is provided by the community through language bindings which
16can be found at the Crossroads website.
17
18
19Building and Installation
20-------------------------
21
22The following instructions apply to building libxs from an official release
23downloaded from the Crossroads I/O website. For building directly from Git,
24refer to the `INSTALL` file included with the libxs distribution.
25
26On POSIX platforms, libxs uses the standard autotools build system. To
27build and install the library, ensure your system has a C++ compiler
28installed, and proceed with the following steps:
29
301. Run `./configure`, then `make` to build the library.
312. Optionally, run `make check` to run the built in test suite.
323. Run `make install` as root.
334. On Linux or other platforms which use `ld.so` for dynamic linking, run
34 `ldconfig` or equivalent as root to update your system's shared library
35 cache.
36
37On Windows, solution files for Visual C++ 2010 are provided in the
38`builds/msvc/` subdirectory of the distribution.
39
40Refer to the `INSTALL` file included with the libxs distribution for more
41detailed installation instructions.
42
43
44ZeroMQ Compatibility
45--------------------
46
47Crossroads I/O provides a drop-in 'libzmq' compatibility library for ZeroMQ
48language bindings and applications. To enable 'libzmq' compatibility, you
49must build your copy of libxs with the `--enable-libzmq` option to
50configure, or on Windows by building the appropriate solution file.
51
52For further details refer to the `doc/xs_zmq.html` or the `xs_zmq(7)`
53manual page included with this distribution.
54
55NOTE: Enabling this option will *overwrite* any existing installation of
56`libzmq` on your system.
57
58
59Reporting Bugs
60--------------
61
62To report a bug, send an email describing your problem to the Crossroads
63mailing list. To make sure your bug report won't be missed, you can file a
64report in the bug tracker[1].
65
66To help Crossroads developers to fix the bug, please try to provide a minimal
67test program, ideally written in C, that reproduces the problem you are
68reporting.
69
70NOTE: The bug tracker exists primarily to track bugs and pertinent data (test
71cases, crash logs, etc.). You should not use it for _discussion_. In the bug
72tracker your audience will be very limited. Mailing list serves the purpose of
73discussing bugs much better.
74
75
76Contributing to the Project
77---------------------------
78
79Before contributing to the project make sure you understand the legal
80implications of doing so. These are outlined on the Crossroads I/O website[2].
81
82To submit your contribution, send it as a patch (using `git format-patch`, `diff`,
83or similar) to the mailing list. Make sure to use your real name, and prefix
84the subject of your post with `[PATCH]`.
85
86All contributions will be reviewed and, if they pass review, accepted. For more
87details refer to the website[3].
88
89
90Resources
91---------
92
93The libxs development Git tree can be found on Github[4].
94
95Development is coordinated on the mailing list[5].
96Visit the archives[6] to join or view archives
97of previous discussion.
98
99Extensive documentation is provided with the distribution. Refer to
100`doc/xs.html`, or the `xs(7)` manual page after you have installed libxs on
101your system.
102
103Further resources, language bindings, tutorials, and more can be found on
104the Crossroads website[7].
105
106
107Copying
108-------
109
110Free use of this software is granted under the terms of the GNU Lesser General
111Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER`
112included with the libxs distribution.
113
114As a special exception, the copyright holders of libxs grant you the right
115to link the library statically with your software. Refer to the end of
116the `COPYING.LESSER` file included with the libxs distribution for details.
117
118Footnotes
119---------
120
121[1]: Bug tracker: https://github.com/crossroads-io/libxs/issues
122
123[2]: Legal information: http://www.crossroads.io/dev:legal
124
125[3]: Code review: http://www.crossroads.io/dev:code-review
126
127[4]: Source code: http://github.com/crossroads-io
128
129[5]: Mailing list: crossroads-dev@groups.crossroads.io
130
131[6]: Mailing list archives: http://groups.crossroads.io/
132
133[7]: Project website: http://www.crossroads.io/
134
README.asciidoc
1Welcome
2=======
3
4Crossroads I/O ("libxs") is a library for building scalable and high
5performance distributed applications. It fits between classic BSD sockets,
6JMS/AMQP-style message queues, and enterprise message-oriented middleware.
7
8Crossroads I/O extends the standard socket interfaces with features
9traditionally provided by specialised messaging middleware products,
10providing an abstraction of asynchronous message queues, multiple messaging
11patterns, message filtering (subscriptions), seamless access to multiple
12transport protocols, and more.
13
14Crossroads I/O provides a native C API for applications. Support for many
15more languages is provided by the community through language bindings which
16can be found at the Crossroads website.
17
18
19Building and Installation
20-------------------------
21
22The following instructions apply to building libxs from an official release
23downloaded from the Crossroads I/O website. For building directly from Git,
24refer to the `INSTALL` file included with the libxs distribution.
25
26On POSIX platforms, libxs uses the standard autotools build system. To
27build and install the library, ensure your system has a C++ compiler
28installed, and proceed with the following steps:
29
301. Run `./configure`, then `make` to build the library.
312. Optionally, run `make check` to run the built in test suite.
323. Run `make install` as root.
334. On Linux or other platforms which use `ld.so` for dynamic linking, run
34 `ldconfig` or equivalent as root to update your system's shared library
35 cache.
36
37On Windows, solution files for Visual C++ 2010 are provided in the
38`builds/msvc/` subdirectory of the distribution.
39
40Refer to the `INSTALL` file included with the libxs distribution for more
41detailed installation instructions.
42
43
44ZeroMQ Compatibility
45--------------------
46
47Crossroads I/O provides a drop-in 'libzmq' compatibility library for ZeroMQ
48language bindings and applications. To enable 'libzmq' compatibility, you
49must build your copy of libxs with the `--enable-libzmq` option to
50configure, or on Windows by building the appropriate solution file.
51
52For further details refer to the `doc/xs_zmq.html` or the `xs_zmq(7)`
53manual page included with this distribution.
54
55NOTE: Enabling this option will *overwrite* any existing installation of
56`libzmq` on your system.
57
58
59Reporting Bugs
60--------------
61
62To report a bug, send an email describing your problem to the Crossroads
63mailing list. To make sure your bug report won't be missed, you can file a
64report in the bug tracker[1].
65
66To help Crossroads developers to fix the bug, please try to provide a minimal
67test program, ideally written in C, that reproduces the problem you are
68reporting.
69
70NOTE: The bug tracker exists primarily to track bugs and pertinent data (test
71cases, crash logs, etc.). You should not use it for _discussion_. In the bug
72tracker your audience will be very limited. Mailing list serves the purpose of
73discussing bugs much better.
74
75
76Contributing to the Project
77---------------------------
78
79Before contributing to the project make sure you understand the legal
80implications of doing so. These are outlined on the Crossroads I/O website[2].
81
82To submit your contribution, send it as a patch (using `git format-patch`, `diff`,
83or similar) to the mailing list. Make sure to use your real name, and prefix
84the subject of your post with `[PATCH]`.
85
86All contributions will be reviewed and, if they pass review, accepted. For more
87details refer to the website[3].
88
89
90Resources
91---------
92
93The libxs development Git tree can be found on Github[4].
94
95Development is coordinated on the mailing list[5].
96Visit the archives[6] to join or view archives
97of previous discussion.
98
99Extensive documentation is provided with the distribution. Refer to
100`doc/xs.html`, or the `xs(7)` manual page after you have installed libxs on
101your system.
102
103Further resources, language bindings, tutorials, and more can be found on
104the Crossroads website[7].
105
106
107Copying
108-------
109
110Free use of this software is granted under the terms of the GNU Lesser General
111Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER`
112included with the libxs distribution.
113
114As a special exception, the copyright holders of libxs grant you the right
115to link the library statically with your software. Refer to the end of
116the `COPYING.LESSER` file included with the libxs distribution for details.
117
118Footnotes
119---------
120
121[1]: Bug tracker: https://github.com/crossroads-io/libxs/issues
122
123[2]: Legal information: http://www.crossroads.io/dev:legal
124
125[3]: Code review: http://www.crossroads.io/dev:code-review
126
127[4]: Source code: http://github.com/crossroads-io
128
129[5]: Mailing list: crossroads-dev@groups.crossroads.io
130
131[6]: Mailing list archives: http://groups.crossroads.io/
132
133[7]: Project website: http://www.crossroads.io/
134