Title : cvs compiled for Mach-O with the cvsgui support
Author : Alexandre Parenteau <aubonbeurre@hotmail.com> --- January 2001
/* $Id: README,v 1.2 2001/01/03 17:53:54 alexp Exp $ */

1) Why a new cvs command for MacOSX ?
  1.1 - HQX and AppleSingle encoding
  1.2 - The line feed problem
  1.3 - The cvs command included with MacOSX is outdated
  1.4 - Signature for files
  1.5 - The MacCvs support for MacOSX

2) How does-it work (for developers) ?
  2.1 - cvs-cvsgui is a patched version of cvs-1.11
  2.2 - the convert scheme
  2.3 - the cvsgui changes
  2.4 - the new file manager

3) How to install, use, compile ?
  3.1 - replacing cvs-MacOSX
  3.2 - preparing a client session
  3.3 - using the environment variables
  3.4 - compilation

1) Why a new cvs command for MacOSX ?

1.1 - HQX and AppleSingle encoding

The cvs command included with MacOSX has several problems when used
with repositories created with MacCvs or MacCvsPro : MacCvs and
MacCvsPro are using an encoding for the macintosh files with
a resource fork (either using the HQX or AppleSingle file format).
These files get encoded on the server and are decoded on the client.

The cvs command included with MacOSX (cvs-MacOSX) will not interpret
correctly this encoding and it will result in a corrupted checked out
file.

cvs with the cvsgui support (cvs-cvsgui) will interpret correctly
the format when checking out and commiting a resource file.

1.2 - The line feed problem

cvs-MacOSX only check-out text file with a Unix line feed, and
it will corrupt a repository if you commit a file with a Mac line
feed.

cvs-cvsgui will optionally check-out text files with the Mac line
feed and allows any text file to be stored with a Mac or Unix
line feed, making it impossible to corrupt the repository.

1.3 - The cvs command included with MacOSX is outdated

cvs-MacOSX is using 1.10.
cvs-cvsgui is using 1.11.

1.4 - Signature for files

cvs-MacOSX does not deal with Mac-signature for text and binaries files.

cvs-cvsgui does deal with Mac-signature, it asks InternetConfig what is
the correct Mac-signature for a newly created file.

It also provides several optional goodies like an ISO8859 conversion
on the text files.

1.5 - The MacCvs support for MacOSX

In the future, the application cvs-cvsgui will be the same used by
MacCvs to launch the cvs commands. No more shared library, the
executable will be the same used by the user interface of MacCvs (and
possibly other programs) and the command line tool.

The reason to go this way (instead of making cvs a Carbon program) is
because we want to use the underlying Unix power of MacOSX from which
cvs can take advantage (server mode, ssh/kerberos...).

On MacOS 8/9, MacCvs will stay the same.

2) How does-it work (for developers) ?

2.1 - cvs-cvsgui is a patched version of cvs-1.11

cvs-cvsgui is a modified version of the latest official tar ball for
cvs-1.11. It introduces several changes related to MacOSX and to the
cvsgui project.

2.2 - the convert scheme

In cvs-cvsgui, there is a new folder named 'macintosh' which
contains the convert scheme used in client mode for maintaining
the macintosh informations on the resource and text files.

This part converts local files to send to the server, and convert
back the server files to the local format.

Local and server file formats may be very different, for example
you may have :

Local:                             Server:

Text file with Mac line feed       Text file with Unix line feed
and Mac-encoding                   and ISO-encoding

Resource file                      HQX file

JPEG file with the JPEG            JPEG file
signature


2.3 - the cvsgui changes

The cvsgui changes are related to the future bridge for MacCvs. It uses
the same system used on Unix for gCvs. It uses a piped session.
Informations go back and forth between the cvs program and MacCvs using
the pipe.

These changes are included inside lib/cvsgui*

2.4 - the new file manager

The macintosh part is using the new file manager (i.e. FSRef). The reason
is because we want to be able to manage long file named and perhaps
Unicode names later on.

This may (or may not) be a problem with the file system you use to
check-out your project. Currently cvs-cvsgui have been tested on
HFS+ only.

3) How to install, use, compile ?

3.1 - replacing cvs-MacOSX

It's not recommended to use cvs-MacOSX with cvs-cvsgui because of the line
feed problems.

I personnaly recommend to disable the existing cvs and to replace it
by the new one:

> cd /usr/bin
> mv cvs cvs.orig
> cp /path/to/cvsgui cvsgui
> ln -s cvsgui cvs

Now try :

> cvs --version

It should say :

> Concurrent Versions System (CVS) 1.11 (client/server)
> ...

3.2 - preparing a client session

The ability of cvs-cvsgui to manage Mac formats work *only* in client
mode. IT WON'T WORK IN LOCAL MODE.

This means that you should have your CVSROOT to use either :pserver:,
:rsh: or :ext: (ssh). There is no Kerberos support right now.

See the cvs doc for more details on how to set-up a client session.

3.3 - using the environment variables

Controlling the Mac informations for the cvs files is done using
environment variables. Environment variables can be set and unset using
the shell command 'setenv'.

Here is an example of my ~/.tcshrc :

> setenv CVSROOT :pserver:alexp@pelforth:/cvsroot
> setenv IC_ON_TXT yes
> setenv MAC_DEFAULT_RESOURCE_ENCODING AppleSingle

* MAC_DEFAULT_RESOURCE_ENCODING (HQX, AppleSingle)

Set which format to use in order to encode files with a resource fork
for sending to the server.

Decoding is not relevant, cvs-cvsgui will pick the appropriate one.

The default encoding is HQX

* ISO8859 (1)

Text files will be converted from the Mac-encoding to a ISO8859 format.
Usefull if you use accentuation accross platforms (French, German...)

The default makes no conversion for text files.

(Note : currently disabled)

* IC_ON_TXT (yes)

If defined, it will use InterConfig to set the Mac signature for any
newly created file (except the files using a HQX or AppleSingle encoding,
because the file type/creator is already enclosed in these formats).

By default the created file do not have a file type/creator.

* CVS_MACLF (yes)

If defined, any newly created text file will have the Mac line feed (0x0d).

By default, the file have a Unix line feed.

* MAC_BINARY_TYPES_PLAIN, MAC_BINARY_TYPES_HQX, MAC_BINARY_TYPES_SINGLE

It contains a semi-colon separated set of types (ex: JPEG;TIFF) and help
cvs to decide which encoding to use on the server for these files.

MAC_BINARY_TYPES_PLAIN will ignore the resource fork of the file
which matches the type.

MAC_BINARY_TYPES_HQX will encode the file which matches the type
in the HQX format.

MAC_BINARY_TYPES_SINGLE will encode the file which matches the type
in the AppleSingle format.

* CVSREAD (y)

This is part of the regular cvs, it let you check-out read-only is
defined.

3.4 - compilation

The source file is Unix tar ball (tar.gz).

Decompress it and use the configure scheme :

> tar zxvf cvsmac-src.tar.gz
> cd cvsmac
> ./configure

It will produce the executable in src/cvsgui. The executable is named
'cvsgui' because the regular 'cvs' name would conflict with the CVS
admin folder on a HFS+ partition which is no-case sensitive.

You may encounter a problem with configure which doesn't find your c++
compiler. If this happens, go in /usr/bin, and type :

> cd /usr/bin
> ln -s c++ g++
