# rubysl-socket

An implementation of the Ruby socket standard library for Rubinius, written
using Ruby and FFI (and a tiny bit of C++ defined in Rubinius itself). More
information about the socket standard library can be found at
<http://ruby-doc.org/stdlib/libdoc/socket/rdoc/index.html>.

Please note that **only** Rubinius is officially supported. While other Ruby
implementations are free to use rubysl-socket according to its license we do not
provide any support for this.

Issues for the socket standard library in general should be reported at
<https://bugs.ruby-lang.org/>, **only** use this project's issue tracker for
reporting issues with the Gem itself (e.g. something isn't implemented
correctly).

## Target

The 2.0 branch of rubysl-socket targets Ruby 2.x, other Ruby versions are
currently not supported.

## Unsupported Features

Currently the use of ancillary data is not supported. While
`Socket::AncillaryData` exists and is implemented for the most part it's not
used by `BasicSocket#sendmsg` and `BasicSocket#recvmsg`. Extracting/building
ancillary data requires the use of platform specific macros and these can't be
easily bound to Ruby via FFI. Using a C extension only adds more complexity for
a feature that will most likely be rarely used, if ever.

## Requirements

* Rubinius 2.10 or newer
* A POSIX compliant operating system

Windows is currently not supported and there are no plans to support it for the
foreseeable future. The Rubinius team sadly lacks the capacity and experience to
support Windows besides also supporting the countless Linux and BSD
distributions out there.

## Installation

By default rubysl-socket is already installed when you install Rubinius.
Currently updating rubysl-socket requires re-installing Rubinius, in the future
you can simply update rubysl-socket by running `gem update rubysl-socket`.

## Contributing

In general the contributing guidelines are the same as Rubinius
(<http://rubinius.com/doc/en/contributing/>). The structure of this repository
is as following:

* `lib/rubysl/socket/`: contains all code living under the `RubySL::Socket`
  namespace, mostly used for FFI code, helper methods, etc.
* `lib/socket/`: contains the code of the public socket APIs such as `Socket`,
  `TCPSocket`, etc. Code in this directory should not refer to the `Rubinius`
  namespace directly, instead use (or create) methods defined under the
  `RubySL::Socket` namespace.
* `spec/`: all mspec specs

To get started, clone the directory and install all Gems:

    bundle install

You'll want to do this for both your local CRuby and Rubinius installations.

Running the specs under CRuby works as following:

    mspec spec/path/to/file_spec.rb

Running the specs under Rubinius requires an extra environment variable so
Rubinius loads the local rubysl-socket copy instead of the installed one:

    RUBYLIB=.:lib mspec spec/path/to/file_spec.rb

All specs **must** pass on both CRuby and Rubinius.

## License

rubysl-socket is licensed under the BSD license unless stated otherwise, a copy
of this license can be found in the file "LICENSE". The MRI source code found in
`lib/socket/mri.rb` is licensed under the same license as Ruby, a copy of this
license can be found in the file itself.