gtk-gnutella

               Copyright (c) 2000-2001, Yann Grossel
             Copyright (c) 2001-2011, Raphael Manfredi

------------------------------------------------------------------------
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc.:
        59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
------------------------------------------------------------------------

This software is currently maintained by Raphael_Manfredi@pobox.com.

If you have problems, your best bet is to subscribe to the gtk-gnutella-users
list on www.sourceforge.net, and more precisely here:

    http://lists.sourceforge.net/lists/listinfo/gtk-gnutella-users

Also visit the main website for news, updates, FAQ, and more at:

    http://gtk-gnutella.sourceforge.net/


Introduction
------------

gtk-gnutella is a GUI based Gnutella servent. It's based upon the original
look of Gnutella v0.5.

It's a fully featured Gnutella servent designed to share any type of file
the user wishes to share.  gtk-gnutella implements compressed gnutella net 
connections, ultra and leaf nodes, Partial File Sharing, Push Proxies and 
uses Passive/Active Remote Queueing (PARQ).

When UDP traffic is enabled, it will increase the feature set: out-of-band
query hit reception, HEAD pings and pongs, Distributed Hash Table (DHT)
lookups for finding alternate sources and push-proxies.

It is compatible with all other Gnutella servents from other vendors: it will
join the same network and exchange with others seamlessly.

It's supposed to work on any Unix-like system, and can be built with either a
GTK+ (1.2 or above) or GTK+ 2.x GUI. Gnome is not required.
gtk-gnutella is currently developed and tested under Linux (Debian 2.2) and is
known to run at least on Linux, FreeBSD, NetBSD, OpenBSD, Darwin, Solaris,
Tru64 UNIX (OSF/1), SGI IRIX, BeOS whereas CPU architectures include x86,
AMD64, PowerPC, SPARC, MIPS.

It is released under the GNU General Public License (GPL).  

For further information on Gnutella, try:
    http://www.the-gdf.com/ 
    http://www.infoanarchy.org/wiki/wiki.pl?Gnutella
    http://rfc-gnutella.sourceforge.net/

The gtk-gnutella Home Page is:
    http://gtk-gnutella.sourceforge.net/

The Project Page is:
    http://sourceforge.net/projects/gtk-gnutella/

Open Discussion Forums, try:
    http://www.gnutellaforums.com/

There is an IRC channel for gtk-gnutella on http://www.freenode.net:
    irc.freenode.net #gtk-gnutella

Mailing lists

    http://lists.sourceforge.net/mailman/listinfo/gtk-gnutella-devel
    http://lists.sourceforge.net/mailman/listinfo/gtk-gnutella-users


Installation
------------

To install one of the precompiled packages, consult your distribution's 
documentation.  

To compile gtk-gnutella:  

    ./build.sh
    make install

The build.sh shell script is a wrapper for Configure. There should almost never
be a need to invoke Configure manually.  The `Configure' shell script attempts
to guess correct values for various system-dependent variables used during
compilation.  It uses those values to create a `Makefile' in each directory of
the package.  It may also create one or more `.h' files containing
system-dependent definitions.  Finally, it creates `config.sh' file that saves
the results of its tests to speed up reconfiguring, reusing your previous
values as defaults.  If you don't want to reuse your previous values you can
delete them with:

    make clobber

A list of available build options is shown if you run
    
    ./build.sh --help

The environment variables CC, CFLAGS, LDFLAGS, PREFIX, MAKE, YACC are
respected if set. The default path prefix is /usr/local. The default
front-end is Gtk+ 2.x. Support for DBUS, GNUTLS, IPv6, NLS, Socker is
enabled by default but will only be used if actually available during
the Configure run.

National Language Support requires at least GNU gettext 0.11.5 or a
compatible implementation which supports its plural model. To disable
NLS (National Language Support) i.e., nationalized text in the user
interface:

    ./build.sh --disable-nls

gtk-gnutella can also be compiled for headless operation the so-called
"topless" mode. The resulting executable won't use or depend on Gtk+
and gtk-gnutella can only be controlled through the remote shell in
this case. If you want a topless gtk-gnutella run

    ./build.sh --topless

The option "official" should be set to "true" unless you want to test
gtk-gnutella from git or are a developer. Currently, an "inofficial" build
will access files in the sources directory to ease the process of testing.
However, the meaning of this option might change at any time.  Therefore,
software distributions and admins are urged to provide "official" builds
only.

For example, a fairly typical configuration for Linux x86, Gtk+ 2.x UI:

    CC=gcc ./build.sh --prefix=/usr

You might have to CFLAGS and LDFLAGS so that the compiler and linker can find
the necessary libraries if they are not installed in the systems default
directories.

Packagers who need to install gtk-gnutella to a special base directory can 
do so with:

    make install INSTALL_PREFIX=/DESTDIR

which will install in /DESTDIR/$bindir, /DESTDIR/$privlib, etc.

If you need to do unusual things to compile the package, please try
to figure out how `Configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If at some point `config.sh'
contains results you don't want to keep, you may remove or edit it.

You can remove the program binaries and object files from the
source code directory by typing `make clean'.  To also remove the
files that `Configure' created (so you can compile the package for
a different kind of computer), type `make clobber'.


Quick Start
-----------

To run gtk-gnutella, launch:

    gtk-gnutella

If you wish to keep track of errors/warning for later perusal,
you may also do:

    gtk-gnutella >gnutella.log 2>gnutella.warn &

Operation is fairly straightforward.  Default values are set for getting 
started, unless you are behind a firewall. This section should get you started 
quickly.

You should have three directories created to store your files, "downloading,"
"done," and "corrupt."

Click on "Config" in the upper left hand box to get the configuration screen, 
then select your downloading, done, and corrupt directories in the "Download 
settings" tab. 

In the "Upload settings" pane, "Path(s) to files" are your shared directories. 
They are the files you will share to the network.  It's easy and convenient to 
share your "done" directory.  When downloaded files are complete, they are 
moved to the done directory and then can be uploaded by others.  Once you have 
selected your shared directories, click the "Rescan" button.  Sharing is the 
whole point of the Gnutella network.  Those who don't share are called 
"leechers" and some people will refuse to share with them.  gtk-gnutella 
offers fine-tuned bandwith control so even if you only have a dialup 
connection, you should devote some bandwith to sharing.  

Click on "GnutellaNet" in the upper left hand box to see how your connections 
are going.  If you see many connection attempts failing, don't worry, this is 
normal.  In extreme cases, it could take 10-30 minutes to get stable 
connections the first time you use gtk-gnutella.  If you don't get a 
connection, quit the program and restart it to get a few more hosts from the 
GWebCache server. If you still don't get connected, you may need to check your 
Internet connection and DNS (etc/resolv.conf) list. If your Mozilla or 
Konqueror web browser isn't working, you have a problem. In normal operations 
you should be connected within 30 or so seconds.

Once you are connected to a few hosts (2 or 3 is good) you can perform a 
search. Click on "Search" in the upper left hand box to get the Search pane, 
then type in a keyword or two. Gnutella uses "AND" for keyword searches, so if 
you type two words both will have to be in the file name to get a return. In 
most situations it takes 60 seconds for search results to be returned. Be 
patient! You are searching about 20,000 hosts.

Once you see a file name you like, click on it and press the button at the 
bottom "Download Selected Files" ("Download selected" in the GTK2 version) and 
the file will be queued for download.  Click on "Downloads" in the upper left 
hand box to see what's going on.

The client is pretty smart and won't "hammer" a host, even if you select all 
the files a host has, if the host is busy it will only try that host every so 
often. Select as many files as you like.

The default search selection option is "Autoselect identical", so when you 
click on a file that several other hosts have, it will automatically select 
any file in the list that is identical. This gives you a better chance of 
completing a file if a host drops off the network. Duplicate names are handled 
in the download manager, so don't worry about that. It's better to wait a 
little bit for all the search results to come in, then click on file names you 
like.

Once a file is in the "done" directory, the download manager will not download 
the identical file again.

There are more features, click around and get used to the program. Most things 
make sense. Visit Gnutella web sites for more information on Gnutella, the 
protocol and network etiquette.


Bug Reports
-----------

This software will always be in a state of development, improvements being 
added all the time. Stable version will be posted from time to time, but your 
feedback is needed by developers in order to make a great program!

There is a Bug Report HOWTO on the gtk-gnutella home page.

Please post any Bug Reports to the Bug Tracker on the SourceForge
project page.


Developers, Programmers and Other Tech Info
-------------------------------------------

The following information is for Developers only.

* Run multiple copies on the same computer:

If you simply do a "make" rather than a "make install" a version of 
gtk-gnutella will appear in your "src" directory. Create a new directory 
called "test1", and copy at least config_gnet and config_gui from 
$HOME/.gtk-gnutella, if you want to use the same settings.

Place the compiled version of gtk-gnutella into that directory, add a 
"download" and "done" directory if you like, and from a shell prompt type 
"GTK_GNUTELLA_DIR=path/to/test1 ./gtk-gnutella". The program will use the 
local config file.  The hosts file will now be read and saved to the local 
directory. If you change the port number in the config file, you can run as 
many copies as you want from different directories. You can also have them 
connect to each other by using IP 127.0.0.1:6346 (or whatever port).

If you set the config variable "stop_host_get" the client will not try to 
connect to any outside hosts, thus you can manually connect to your local 
IP:port of the other client you have running for testing. It won't timeout the 
host because of inactivity like it normally would.

* Debug variable use:

A config variable called "dbg" is used to print debug information to the 
terminal window. It has 10 levels, the higher the level, the more information 
is printed. Don't set it to 10 unless you like to see way too much 
information! Data such as raw search packets are shown at level 7.  Small 
warnings and other stuff is found at level 1 or 2.

* Developer info:

Feel free to sign up and participate in the mail list. To get up to speed, you 
might want to read some of the past messages in the archives and see what we 
have been up to lately.

If you want contribute code, please follow the style guide, as described in
the doc/devguide/STYLE file.

Read the "Development" and "Developers Howto" pages on the gtk-gnutella home 
page. 

Please, use the patch tracking system found on the main development page to post
any patches you may have come up with. It allows you to upload the patch
file as a binary. Posting to a mailing list usually wraps lines and messes
up a patch file, although you can attach files. You should let everyone on the 
mail list know that you posted a patch to the patch tracker.

If you find bugs, please use the bug tracker on sourceforge (or fix
them!).  Once you get a copy from git (see the git page for instructions),
and you make some modifications, from a shell make sure you cd into the
"gtk-gnutella" directory, type "git diff > output-diff.txt" and a patch
file will be created, referencing the current git version.  You can then
upload this file so others can patch their version with your changes.
If your patch requires other patches, you should include them also.
Before starting a big project, you may want to ask the list if anyone
else is working on that fix so you don't duplicate work.

/* vi: set et ts=4: */