User's Guide - 2. First Time Installation

During first time installation, a base system with the package management tools is installed on your machine. After that you must set up your shell environment to use the software installed by Fink. You only need to do this once; you can upgrade any Fink installation in place, without reinstalling. This is covered in the Upgrading chapter.

Once you have the package management tools installed, you can use them to install more software. This is covered in the Installing Packages chapter.

2.1 Installing the Binary Distribution

The binary distribution comes as a Mac OS X installer package (.pkg), wrapped in a disk image (.dmg). After downloading the disk image from the download page (you may have to use your browser's "Save Target as..." or "Download to Disk" function), double-click it to mount it. Open the "Fink 0.x.x Installer" disk icon that appears on your desktop (or wherever you downloaded it) after Disk Utility has verified the file. Inside you'll find some documentation and an installer package. Double-click the installer package and follow the instructions on screen.

You will be asked for an administrator password and shown some texts. Please read them - they may be more up-to-date than this user's guide. When the installer prompts you for a drive to install to, be sure to pick your system volume (the one on which you installed Mac OS X). If you pick the wrong volume, the install will proceed, but Fink won't work afterwards. When the installer is finished, proceed with the Setting Up Your Environment section.

2.2 Installing the Source Distribution

The source distribution comes as a standard Unix tarball (.tar.gz). It contains only the fink package manager and will download the source for packages on the fly. You can get it from the download page. Older versions of StuffIt Expander have difficuly with handling long file names, so if you have any problems you'll need to remove the folder it generates and follow the command-line instructions below.

The source release must be installed from the command line, so open Terminal.app and change to the directory where you put the fink-0.27.x.tar.gz archive. Your web browser may have partially extracted the archive; in this case you will have fink-0.27.x.tar in your download directory, and you should skip the first command below. The following commands extract the archive:

gunzip fink-0.27.x.tar.gz
tar -xf fink-0.27.x.tar

That creates a directory with the same name as the archive. We'll just keep on using the placeholder fink-0.27.x here. Now, change into that directory and run the bootstrap script:

cd fink-0.27.x
./bootstrap

The script will run some checks on your system and use sudo to become root - that will prompt you for your password. Then, the script will ask you for the installation path. Unless you have a good reason, you should use the default - /opt/sw. Only that will allow you to install downloaded binary packages later on. Also, all examples use that path; be sure to substitute your actual path if you use a different one.

Next up is Fink configuration. You'll be asked for things like proxy and mirror settings and whether you want verbose messages. If you don't understand a question, just press return to accept the default choice. You can re-run this process later using the fink configure command.

When the bootstrap script has all the information it needs, it will start to download the source code for the base system and compile it. No further interaction should be necessary at this point. Don't worry if you see some packages being compiled twice. This is required because to build a binary package of the package manager, you first must have the package manager available.

When the bootstrap is finished, proceed with the Setting Up Your Environment section.

2.3 Setting Up Your Environment

To use the software installed in Fink's directory hierarchy, including the package management programs themselves, you must set your PATH environment variable (and some others) accordingly. Current Fink versions do this automatically, and typically you will just need to open a new Terminal.app window to ensure that these settings are applied. However, in some instances you will need to proceed manually.

In most cases, you can do this by entering the command

/opt/sw/bin/pathsetup.sh

in a terminal window.

Note that for some older versions of fink the program was called pathsetup.command, and one could run it via open /opt/sw/bin/pathsetup.command.

However, if this doesn't work for some reason, you can configure it manually. This will depend on the shell you are using, however. You can determine the shell you are using by opening a terminal and running the command:

echo $SHELL

If it says "csh" or "tcsh" in it, you are using the C shell. If it is bash, zsh, sh, or something similar, you are likely running a variant of the bourne shell.

Bourne Shell (default on Mac OS X 10.3 and later)

If you use a Bourne style shell (e.g. sh, bash, zsh), add the following lines to the file .profile in your home directory (or, if you have an existing .bash_profile file, you should use that instead):
```
. /opt/sw/bin/init.sh
```
If you don't know how to add the line, run these commands:
```
cd
pico .profile
```
You are now in a full-screen (well, full terminal window) text editor and can simply start typing the . /opt/sw/bin/init.sh line. It's okay if there is a note that says "New file". Be sure that you pressed Return at least once after the line, then press Control-O, Return, Control-X to get out of the editor.
C Shell (default on Mac OS X 10.2 and earlier)

If you use tcsh, add the following line to the file .cshrc in your home directory:
```
source /opt/sw/bin/init.csh
```
If you don't know how to add the line, run these commands:
```
cd
pico .cshrc
```
You are now in a full-screen (well, full terminal window) text editor and can simply start typing the source /opt/sw/bin/init.csh line. It's okay if there is a note that says "New file". Be sure that you pressed Return at least once after the line, then press Control-O, Return, Control-X to get out of the editor.

There are a couple of common situations where you may need to edit additional files:
1. You have a ~/.tcshrc.
  
  Such a file occasionally gets created by third-party applications, or you may have done it yourself. In any case what will happen is that ~/.tcshrc gets read and ~/.cshrc is ignored. The recommended procedure is to edit ~/.tcshrc in a similar manner to how you edited ~/.cshrc above, and add the following line at the end:
```
source ~/.cshrc
```
  That way, if you ever need to remove ~/.tcshrc, you will be able to run Fink.
2. You followed the instructions under /usr/share/tcsh/examples/README.
  
  These instructions tell you to create a ~/.tcshrc and a ~/.login . The problem in this case is with ~/.login, which gets run after ~/.tcshrc, and sources /usr/share/tcsh/examples/login. The latter contains a line that overwrites your previous PATH setup. What you should do in this case is create ~/Library/init/tcsh/path:
```
mkdir -p ~/Library/init/tcsh
  pico ~/library/init/tcsh/path
```
  and put:
```
source ~/.cshrc
```
  in it. You should also modify your .tcshrc as in item 1 above, to make sure that your PATH is set correctly for situations where ~/.login doesn't get read.
Editing .cshrc (and other startup files) will only affect new shells (i.e. newly opened Terminal windows), so you should also run this command in all Terminal windows that you opened before you edited the file. You'll also need to run rehash because tcsh caches the list of available commands internally.

Note that the init.sh and init.csh scripts also add /usr/X11R6/bin and /usr/X11R6/man to your PATH so you can use X11 when it is installed. Fink packages have the ability to add settings of their own, e.g. the qt package sets the QTDIR environment variable.

Once your environment is set up, you will need to grab package descriptions as per the Upgrading Fink chapter under Upgrading the Source Distribution, and then proceed to the Installing Packages chapter to see how you can install some actually useful packages using the various package management tools included in Fink.

Next: 3. Installing Packages