1999-09-12
							Emil Brink

			Symbolic Links in gentoo

1. INTRODUCTION
This little document introduces the support for symbolic links that
was introduced in version 0.11.7 of gentoo. This support replaces
the old one that was removed as of version 0.11.1. Sorry about the
delay. :)


2. WHAT IS A SYMBOLIC LINK?
A symbolic link, also known as a soft link or symlink, is a special
file that contains a pathname of some other file. Whenever the link
is accessed by the filesystem, it will use the contained pathname
instead, thus "following the link". Note that the contents of a
symlink need not be the pathname of an existing file; you can use
symlinks to store arbitrary data. At least on Linux systems, the
maximum length of the contents part of a symlink seems to be 1023
bytes.
	In the shell, you can create symbolic links by using
the "ln" (for link) command, with the option "-s" (for symbolic).
For more information, see the man page for ln(1).


3. SYMLINKS IN gentoo
Symbolic links are treated *transparently* by gentoo whenever
possible. This means that gentoo will treat the link as its dest-
ination, rather than as a link. Since referencing other files is
what symlinks are for, I think it's reasonable to treat them as
if they were in fact the files they're pointing at. This is
consistent with the way standard shell commands (cd, ls) treat
symlinks.
	This transparency includes gentoo's typing and styling
system: a symbolic link to e.g. a PNG image will use the type
and style defined for PNG images, and will respond accordingly when
double clicked on. It also includes sorting: links to directories
will sort together with the directories.
	However, the transparancy is only partial. The information
shown in a dirpane row for a symbolic link includes mostly data
about the link itself, not its destination. This means that things
like size, protection flags, and dates all refer to the link itself.
The only column that shows information about the link target is
the Icon column (if present).
	This partial transparancy means that in a listing, you will
be able to spot the links from the regular files quite easily:
	First, if you enable type characters for the Name column
of the panes, the links will have "@" symbols appended to their
names.
	Second, if you enable link destination display (also for
the Name column), links will display an arrow ("->") plus the name
of the link target. So, if you enable both of these features, a
symbolic link called "image" to a PNG file called "picture.png"
will display as "image@ -> picture.png".
	Third, the protection flags for a symbolic link will have
the letter 'l' (for link, of course) in the leftmost position.


4. WORKING WITH SYMLINKS
Of course, gentoo could not be said to really support symlinks if
they could only be used "passively". So, gentoo includes a set of
builtin commands to actively work with symbolic links.

4.1 SymLink
The SymLink command works much like the Copy command. For each
selected source file, it will create an absolute symbolic link
in the destination pane, pointing at the source file.

4.2 SymLinkAs
This command works like the CopyAs command; for each selected
source file, it will display a dialog asking you for a link name,
and then create a symbolic link in the destination pane, with the
given name, and pointing at the source file.

4.3 SymLinkClone
Continuing the analogy, this command works like Clone. It will ask
for a link name for every selected source file, and then create an
absolute link in the *source* pane. Handy when working with shared
libraries, since those tend to use lots of links in the same
directory.

4.4 SymLinkEdit
This command works in two distinctly different modes depending on
the active pane's selection when the command is run.
	If there is a selection, the command will pop up a window
for each symbolic link in the selection, allowing you to directly
edit the link destination in a text entry field. There is also a
button popping up a file selection dialog, thus letting you locate
the desired link target easily. When you click "OK", the current
link will be modified to point at the new target.
	If there is no selection, the command will pop up a dialog
letting you enter both the name and the contents of a link. When
you click "OK" (or press RETURN), the specified link will be cre-
ated. In this mode, the command is analogous to the shell command 
ln mentioned above. NOTE: It is possible to completely replace
ordinary files and directories with symlinks -- the SymLinkEdit
command will require you to confirm any such operation.


5. OTHER COMMANDS
This section contains some information about how other commands
in gentoo deal with symlinks. It is far from complete.

5.1 Information
The Information command has been extended to also show the contents
of symbolic links. The other information it displays (location, size
et cetera) is for the link itself, not its destination. This is
in keeping with the dirpanes, and seems logical to me. A future
version of gentoo may extend the Information command to maybe show
both link and target data in the same window...

5.2 Copy and Move
Both the Copy and the Move commands will _not_ operate transparantly
on symlinks: they will copy (or move) the link itself, not its
destination. There is currently no way of changing this behavior.
	The reason for this is simply that I find it more useful,
and also a bit more logical: when you copy or move an object, you
expect to either get one more of that object, or to move the object
to a new location. If Copy would follow the link, it would produce
one more of the actual link destination, leaving the number of links
unchanged. Or something.
	This behavior is different from that of common shell
commands (cp, mv). Beware.