ipscan/ext/rocksaw

$Id: README 6877 2006-04-14 00:56:38Z dfs $

=====
ABOUT
=====

RockSaw is a simple API for performing network I/O with raw
sockets in Java.


============
REQUIREMENTS
============

The 0.4.5 version of RockSaw has been compiled and tested on Linux,
Win32 with Cygwin/MinGW/Winsock or Visual C++, and Solaris 8/9/10.  It
should compile on other POSIX systems using the GNU tool chain.

The Ping.java example program requires VServ TCP/IP version 0.7.x
(http://www.savarese.org/software/vserv-tcpip.html) or later to
compile because it uses the ICMPEchoPacket class.

librocksaw.so in the binary distribution is pre-compiled for Linux
i386 and rocksaw.dll is pre-compiled for Win32 using Visual C++.

J2SE 1.3 or greater is required to compile because of the use of
Runtime.addShutdownHook on Win32.  If you have a need to support
J2SE 1.2, we can find another solution for calling WSACleanup on
Win32 platforms.

Winsock2 (ws2_32.dll) is required on Win32 platforms.

=========
COMPILING
=========

You must have the JDK_HOME environment variable set and pointing to
the directory where the Java Development Kit is installed.  Otherwise,
the JNI headers will not be found.  RockSaw has been tested primarily
with J2SE 5 JDK 1.5, but it compiles with the J2SE 2 1.3, and 1.4
SDKs.  Only the Ping.java example program requires J2SE 5.

The source code requires Apache Ant (http://ant.apache.org/), GNU
make, and GCC to compile.  On Windows, you must either have Visual C++
installed or have Cygwin and MinGW installed with support for the
Cygwin GCC -mno-cygwin option (http://www.cygwin.com/).  Autoconf
support may be added somewhere down the line if warranted.

The command

  ant -projecthelp

will list all build targets in build.xml.  There are very few files
in the source tree:

  src/java  Java source code
  src/jni   The C JNI source and Makefile

When you compile the source with

  ant jar

the C source will also be built by execing a call to gmake in src/jni.
A jar file and shared library will be created and placed in the lib/
directory.  They will be called:

  rocksaw-version.jar
  librocksaw.so

Currently there is no version number for the shared library.  On
Win32 systems, the shared library will be called:

  rocksaw.dll

The version of Winsock linked to on Windows can be changed with
the jni.winsock property.  By default, it is set to ws2_32,
which is Winsock2.

J2SE 1.4/1.3/1.2
------------------

You may have to override the javac.args, javac.source, and
javac.target properties because the -Xlint:unchecked parameter
is only valid for J2SE 5.  For example, to compile for
J2SE 1.3:

 ant -Djavac.args="" -Djavac.source=1.3 -Djavac.target=1.3 jar

Win32: CYGWIN
-------------

When compiling with cygwin, you may need to redefine the jni.make
property because it is set to "gmake" by default.  Cygwin doesn't
include a gmake executable for GNU Make.  It is named only make.
Therefore, you may have to use the following command line:

  ant -Djni.make=make jar

Alternatively, you can edit the build.properties file.

Win32: Visual C++
-----------------

To compile using Visual C++, you have to override the default
compiler command, make command, and makefile properties:

  jni.cc
  jni.make
  jni.makefile

You can override these on the command line or in build.properties.
For example, to compile using Visual C++, you would use the
following command:

  ant -Djni.cc=cl -Djni.make=nmake -Djni.makefile=Makefile.win32 jar

Make sure your JDK_HOME environment variable is set and that
you've run either the vcvars.bat or vsvars32.bat command
(depending on the version of Visual C++ you're using) to set
your paths for the command line tools.

Ping Example
------------

The example Ping program can be compiled separately with the
example.compile target, but requires VServ TCP/IP to compile.  The
classpath.vserv-tcpip property in build.properties must point to the
VServ TCP/IP jar, which by default is expected to be present in the
lib/ directory.  Then you can compile the program with:

  ant example.compile


=========
LICENSING
=========

RockSaw is Copyright 2004-2005 by Daniel F. Savarese and licensed
under the Apache License 2.0 as described in the files:

  LICENSE
  NOTICE


=====
NOTES
=====

On most operating systems, you must have root access or administrative
privileges to use raw sockets.

The API is at a fairly crude stage of development (i.e., the minimum
required to do the job it needed to do), but is functional.  Don't
hesitate to submit patches that enhance the functionality.


=======
CONTACT
=======

To contact me see http://www.savarese.org/contact.html