freebsd/usr.bin/ncftp/README

If you are a novice user, and don't know how to compile things, try
contacting your local guru first (get them to do it for you :-).  Please
understand that I don't have time to walk newbies through the whole
installation procedure.

One of these months, I will write a Configure script that does all this for
you. I just don't have time to learn another language (dist-3.0) just to
write the script! Perhaps for 2.0.

1. READ this entire file.  Part A, below, tells what to do if you want to
   use NcFTP with a command-line editor.  Part B tells you how to configure
   the Makefile to compile the program for your system.  Part C tells you
   how to configure NcFTP's optional features.  Part D tells you how to
   contact me if you want to report a bug or submit new code to the
   program.

2. EDIT the Makefile, making any necessary changes described in parts
   A, B, or C.  Don't forget to read the directions in the Makefile,
   so you don't forget any needed libraries, etcetera.

3. You can also change the program's default behavior by editing defaults.h.
   99% of the time you don't need to do this, so you can skip this step.

If you have problems, you can mail me, but please try your best to install
it without my help.  I'm quite tired of responding to lazy SunOS users
because they didn't bother reading the directions so that they would have
known that they needed to use GCC.  

I _do_ want to hear from you if you have comments or bug reports/fixes.  I
would also like to hear from you if you had a system that wasn't covered
in sys.h, so I can add an entry for other users of your system.

The latest version of ncftp is available in the directory:
	cse.unl.edu:/pub/mgleason
This machine is heavily used by students and faculty alike, so please
do not call during working hours (9AM - 5PM American Central time).  In fact,
I have a cron entry that changes all the file permissions to public
unreadable during that period, so you won't be able to download anyway.

I am grateful to Shari Deiana and the University of Nebraska for making this
possible!


Part A.  Installing with a command line editor:
----------------------------------------------

As of this release, GNU Readline and Chris Thewalt's Getline command-line
editing and history facilities are supported.  Neither are included with the
ncftp sources.  You can find Getline at:
  ce.berkeley.edu:/pub/thewalt/getline.tar.Z  (note: use 'ls', not 'dir!')
and Readline is in the directory:
  prep.ai.mit.edu:/pub/gnu

To install Readline, you will need to know where libreadline.a and the
header <readline/readline.h> are.  You will need to link libreadline.a and
libcurses.a (or libtermcap.a) with ncftp (see the Makefile).  Good luck on
trying to compile it.  It is not an easy thing to do!  In the Makefile, you
will need to add -DREADLINE to PDEFS, add -lreadline -lcurses to LIBS, and
edit the HDRDIRS and LIBDIRS lines.  This stuff is already in the Makefile,
so you can just uncomment it.

To install Getline, you need to know where libgetline.a and it's header
(getline.h) are.  In the Makefile, you'll need to add -lgetline to LIBS and
edit the HDRDIRS and LIBDIRS lines.  This stuff is already in the Makefile,
so you can just uncomment it.

DO NOT bug me if you can't figure out how to compile Getline or Readline.
Contact their respective authors instead.  It is not essential that you use
them.


Part B.  System Dependencies:
----------------------------

NcFTP may need work-arounds for some things due to the differences
in implementations of unix.  The following systems are taken care
of automatically.  For these systems, you should just be able to type
'make' (but proceed to part C):

   Silicon Graphics IRIX
   IBM's AIX
   SINIX
   DEC's Ultrix (well, might need to use -lcursesX instead of -lcurses)
   NeXT
   Pyramid OSx
   Berkley Software Design, Inc.'s BSDi

Otherwise you will have to configure ncftp manually.

Important for "Yellow Pages" users:  Don't forget to link the library
that includes the YP/NIS version of getpwuid(), etc.  Otherwise the program
won't be able to expand ~username/path/name type pathnames, and maybe even
~/path/name types of pathnames.  If you're wondering why the program isn't
opening your rc file, this could be the cause.

You will need to add these things to the SDEFS line in the Makefile
as applicable.  As an example, if I say 'add -DFoobar to SDEFS,' find
the line in the Makefile that reads 'SDEFS=' (or 'SDEFS=-DFoo2') and
change it to 'SDEFS=-DFoobar' (or 'SDEFS=-DFoo2 -DFoobar).  If your
system is listed below, follow the directions and then you ready to
go to part C, below.

    Sun Microsystems' SunOS/Solaris:  Use an ANSI compiler such as
      gcc (set CC=gcc in the Makefile), or acc (set CC=acc).
      The regular 'cc' is not an ANSI compiler.  You could also run
      something like 'ansi2knr' on the sources and hope it works.
	  You will probably need to link both the curses and termcap
	  libraries if you use -DCURSES (see below).  If you're running
	  Solaris (SunOS 5.x or greater) add -DSolaris to SDEFS.
	  I also needed to add -lnsl -lsocket to LIBS.

    Hewlett-Packard HP-UX:  If you have 7.0, you'll need to find
      a copy of <ftp.h> from somewhere (8.0 has it though). Then
      set CFLAGS= -Aa.  You may also need to use gcc if your
      compiler is non-ANSI.  Note that for HP-UX, the default
	  terminal escape codes are for HP terminals, so you should
	  probably link termcap/curses in so it will get the ANSI
	  sequences if you're on a vt100, etc., terminal connected
	  to your HP-UX machine.

	Linux:  For 'term' support, from what I can tell just add
	  the path of 'client.a' to LIBS, and add -DTERM_FTP to SDEFS,
	  to turn on the term specific ftp code.  May need to link
	  -lcurses and -ltermcap.
      
    SCO Unix:  Add -DSCO324 or -DSCO322 (as appropriate) to SDEFS,
      and -lsocket to LIBS.

    SCO Xenix 2.3.4: Add -DSCOXNX to SDEFS;
		Try adding -DLINGER if puts don't work.
		Add "-lsocket -ldir" to LIBS.

    Bull DPX/2: Add -DBULL to SDEFS, add -linet to LIBS, and
      use gcc.

    Sequent's DYNIX: Use gcc and add -DDYNIX (if necessary) to SDEFS.
      You may also be short several string functions which you will
      have to get elsewhere, and perhaps mktime and strftime.
	  You can get all that stuff from the BSD sources (like ftp.uu.net).
	  Please bug Sequent to update their libc library!

	Sequent's Dynix/PTX:  Add -DDYNIXPTX to SDEFS.
	  Add -lsocket -linet -lnsl -lseq to LIBS.

    DEC OSF1/1.3:  Use gcc, Add -DGETCWDSIZET to SDEFS.  cc might work,
	 though.  Try cc if gcc chokes.

If your system doesn't fit any of those, things will be trickier.  Answer
all these questions and add to the SDEFS line.  You may want to try
each option one at a time until everything works.

*  Is your system closer to System V or BSD?  Your SDEFS line should have
either -DBSD or -DSYSV.  If you don't know, try leaving it blank first;
some compilers automatically define it for you.

*  Add -DNO_CONST if your compiler chokes on the const directive.  You
will know if you need to add this if the compiler spits out errors saying
it doesn't know what 'const' is.

*  As I said above, you will need to link special libraries if your system
is running Yellow Pages.

*  Add -DSYSSELECTH if you need <sys/select.h> included for definitions
of fd_set, etc.

*  Add -DNO_UNISTDH if you don't have <unistd.h>.  If the compiler complains
about not being able to open <unistd.h> add this.

*  Add -DNO_STDLIBH if you don't have <stdlib.h>.  If the compiler complains
about not being able to open <stdlib.h> add this.

*  Add -DNO_UTIMEH if you don't have <utime.h>.  If the compiler complains
about not being able to open <utime.h> add this.

*  Add -DNO_MKTIME if you don't have the mktime() system call, and don't
feel like getting the source for it and compiling it in with the program.
If you define this, the program will not set the file modification times
to match the ones on the remote host (no big deal).

*  Add -DGETPASS if you would rather use the standard getpass() system
call, instead of our version, Getpass(), which takes more than 8
characters.  You may want to define this if you are having problems
compiling getpass.c.

If you haven't given up on our Getpass(), you can try adding -DSGTTYB
if you want to use a struct sgttyb instead of a struct termio.  By default,
BSD systems define SGTTYB automatically.  You can also try adding -DTERMIOS
to use a POSIX compliant struct termios instead.  Don't pull your hair out
trying to get the Getpass code to compile;  if it gives you problems just
define -DGETPASS and hope your system's getpass can handle passwords
longer than 8 characters.

*  Add -DBAD_INETADDR if your inet_addr() function returns a struct in_addr
instead of a u_long, as it should (in DG/UX 5.4.1).

*  Add -DBROKEN_MEMCPY if ncftp mysteriously dumps core when trying to open
a remote host.  I'm told that this happens because of some problem in System
V's sockets don't like fprintf (and memcpy).

*  Add -DPTRTYPE=char if your pre-ANSI compiler complains about the
way malloc() or free() are used, and in general does not like (void *)
as a generic pointer type.

*  Add -DNO_STRFTIME if your system does not have strftime().  If you do,
we won't try to use it.  This means, however, you cannot use ``%'' values
in your prompt.

*  Add -DNO_RENAME if your system does not have rename() (or the one it
has is broken).  If you do, we will use our own.

*  Add -DNO_STRSTR if your system does not have strstr().  If you do, we
will use our own.

*  Add -DLINGER if puts to the remote system are incomplete.

*  Add -DNET_ERRNO_H if you need to include <net/errno.h> for definitions
   of ECONNREFUSED, etcetera.

*  (Optional) Add -DGETCWDSIZET if your system's getcwd() takes a size_t
as the second parameter instead of an int.

*  (Optional) Add -DHERROR if you know you have the herror() system
call.

*  (Optional) Add -DU_WAIT if you know your wait system call takes
a pointer to a 'union wait.'  Defined automatically if you define
BSD.

*  (Optional) Add -DHOSTNAME=\"machine.domain.nam\" if your system
doesn't generate it's own hostname.  To check this, compile ncftp
then run it and type 'set.'  Look at the variable anon-password.
If the hostname is wrong, or if it is in the form of 'yourlogin' or
'yourlogin@machine' instead of 'yourlogin@machine.xxx.yyy,'
re-compile it with HOSTNAME set to your machine's address, in the
form of 'machine.xxx.yyy.'

*  (Optional) Add -DHAS_DOMAINNAME if you have the getdomainname()
   function.

*  (Optional) If you're having problems with your hostname not being
full (i.e you have 'yourlogin@machine') all is not lost.  First of all,
define HAS_DOMAINNAME if you can.  But sometimes getdomainname() doesn't
work -- instead of giving you the domain name, it returns an empty
string.  So you can hardcode the domain name by defining DOMAIN_NAME to
be the domain (i.e. add -DDOMAIN_NAME=\"domain.nam\").  That way, if
getdomainname doesn't work, the program will have something to fall back
on.  This problem is common on SunOS/Solaris.

*  (Optional) Add -DSTRICT_PROTOS if your compiler wants function prototypes
for all functions, not just non-int-returning ones.  This is really just
handy for debugging during development, so this is not recommended.


Part C.  Program Options:
------------------------

Add these as applicable to the PDEFS line in the Makefile.

* -DGZCAT=\"path\": If you have the GNU gzip package installed on your system,
	the program can try paging remote files compressed with gzip _and_ 
	compress (instead of just compress).  Add -DGZCAT=\"/full/path/to/zcat\"
	with GZCAT set to the path name of GNU's zcat/gzcat.

*   -DCURSES:  Uses curses library to display boldface, underline, etc.
    By default ncftp uses hard-coded ANSI escapes (^[[1m etc.) to
    save the 100k or so the curses library adds.  You will also need
    to edit the LIBS line in the Makefile to add -lcurses.  You may
	need to add -ltermcap instead, or both -lcurses and -ltermcap.
	If you choose to use the termcap library, you may want to also add
	-DNO_CURSES_H so it does not try to include <curses.h>.

*   -DSYSLOG:  Define this to have ncftp log connections and transfers
    to the syslog.

*   -DNO_TIPS:  Define if you want to cut a little fat at the expense of
     novice users.

*   -DGETLINE: If you want to use Chris Thewalt's getline input line editor
    and history facility, add this (and see below).

*   -DREADLINE:  If you want to use GNU's readline input line editor and
    history facility, add this (and see the Makefile). If you do this, you
    also need to add -DCURSES (see above).

*	-DSOCKS: NcFTP is now compatible with the Socks library by David Koblas,
	at koblas@sgi.com.  This lets you use NcFTP with a "firewall" gateway
	for enhanced site security.  You can get the latest version from...
		ftp://ftp.netcom.com/pub/ko/koblas/

	After you have compiled it, compile NcFTP
	with -DSOCKS added to PDEFS, and the pathname of the Rconnect.o file
	added to LIBS.
	
*	-DTRY_ABOR:  Define if you want to try the 'ABOR' command from ncftp;
	The aborting code has had some problems, so by default the program
	'aborts' by continuing to read input but not echoing output.

*   -DDB_ERRS:  Define this if you want my Perror() function to be more
	verbose.  You may want to do this if you are a programmer examining this
	code, and want to know where in the source the Perror's are coming
	from.

Part D.  Sending me patches:
---------------------------

I apologize in advance for problems that my coding style may cause.  The code
itself is formatted such that each indent-level is a tab (intended to be
equivalent to 4 spaces), and not spaces nor a combination of tabs and spaces.
The reason for this, besides being more logical to me, is that I use a
Macintosh editor to compose the code and I prefer it's indenting method.
Another problem in my coding-style is that I write C-code intended for ANSI
C compilers.  This means that I will use the new-style function declarations
and function prototypes, like:


   long Foobar(long, long, char *);
   long Foobar(long t0, long t1, char *str)
   {
   }

as opposed to:

   long Foobar();
   long Foobar(t0, t1, str)
	   long t0, t1;
	   char *str;
   {
   }

Another thing may annoy you is that I always use function prototypes for any
function I call, including functions that return an int.  This is a good
practice that I learned from the Macintosh programming world.  

So if you send me patches, please conform to my coding style so that 'patch'
won't screw up, and also that some continuity will be preserved.

Before you make your patch, you should be sure that you are using the most
current version of the program.  This is especially important if you are
reporting a bug; I may have already fixed it!  See the above info to get it
via ftp.  Major versions are always posted to comp.sources.misc.  Bug reports
are posted to comp.sources.bugs.  Patches that need to be posted ASAP are
posted to this group first, so it is advisable that you check this group.

If you make changes to the code, surround your code in #ifdef/#endif blocks.
Instead of doing things like #ifdef SunOS, use a name that describes the
bug fix or feature, and not your system type, like #ifdef NO_UNISTDH,
or #ifdef GETLINE.  That way in case another system has the same problem,
it can be added to sys.h without cluttering up the source code.  Then, add
the symbol you used to the end of cmds.c, in the 'CPP Hell' part of the
version() command.  You'll see a list of CPP symbols, so just add yours in
a similar fashion, like #ifdef GETLINE/DStrs[nDStrs++] = "GETLINE";/#endif.

If you don't know how to make a patch, here's how to do it.  Things are easy
if you've only changed one file.  Then all you need to do pipe the output of
diff -c into a file and send it to me, i.e. "diff -c cmds.c cmds.c.hack >pch."
If you've hacked several files, the way I do it is to keep the originals in
one directory (you did make a copy of everything first didn't you?) and the
revisions in another directory.  Then you change directory to the one with the
originals and do "diff -c . ../revisions > ../pch."

--mg (mgleason@cse.unl.edu)