FreeBSD offers two primary methods of downloading applications and system tools: packages and ports. Users will have to choose between the two collections when installing these tools. Packages are pre-compiled binary packages, typically smaller in size than full port installations and they do not require compilation time. However, ports are a much more customizable option, allowing users to directly interact with the build process and configure the application to their preference. Additionally, installing an application from a port can help a user understand how the application is compiled, configured, and finally built into a binary. It can be a very rewarding process!
For this guide, we will be compiling
irssi, a powerful and modular text-based Internet Relay Chat (IRC) client, from the Ports Collection.
NOTE: ensure that you run all the following commands as the root user by running
$ sudo su once.
Before we start, ensure you have a working installation of FreeBSD. If you do not, you can follow these installation walkthroughs:
- If you’d like to keep your primary operating system on your computer and install FreeBSD in a virtual machine, click here: Installing FreeBSD with VirtualBox
- If you want to use FreeBSD as your primary operating system, but also want it preconfigured and ready to go with a Graphical User Interface (GUI), click here: Installing PC-BSD as a primary operating system
Once you have FreeBSD installed, start up your machine and boot into FreeBSD. If you installed FreeBSD or a similar variant (e.g. PC-BSD, TrueOS, etc.), powering your machine on will automatically boot into the operating system. Furthermore, if your installation includes a GUI, open up a terminal emuluator program such as (e.g. xterm, QTerminal, etc.) and continue with this guide.
To do this on VirtualBox, open the application, select your FreeBSD machine, and click “Start”:
You’ll see a FreeBSD boot menu pop up: let it automatically boot and bring you to the login screen.
Then, after logging in, you should see a welcome screen and a shell prompt appear similar to this:
You are now ready to get started!
1. Setup the Ports Collection:
To begin installing ports on our FreeBSD system, we must first download the Ports Collection. The following command will download the latest compressed snapshot of the Ports Collection and extract it into the
$ portsnap fetch extract
Later on, if we want to update our snapshot of the Ports Collection, we can run:
$ portsnap fetch update
2. Navigating the Ports Collection
Now that the Ports Collection has been installed, we need to be able to find applications that we want to install on our system. The Ports Collection contains directories for software categories, and inside each category are subdirectories for individual applications. We will determine the relevant information necessary to navigate to the
Visit the official FreeBSD ports website and click on “Listed by Logical Group” in the sidebar on the left. Here, we can browse the list of applications available as ports in each category. We can also search for applications using the highlighted search bar.
irssiand take note of the category and package name of the application from the results page.
Navigate to the application’s directory in the Ports Collection, substituting in the category name and package name you noted earlier:
$ cd /usr/ports/CATEGORY_NAME/PACKAGE_NAME
In our example, the category name is “irc” and the package name is “irssi”, so you would type:
$ cd /usr/ports/irc/irssi
3. Installing the Port
Now that we are inside the directory for the
irssi port, we can begin understanding the installation process. This application directory, called the port skeleton, contains a set of files that tells FreeBSD how to compile and install the program. Each port skeleton includes these files and directories:
Makefile: contains statements that specify how the application should be compiled and where its components should be installed.
distinfo: contains the names and checksums of the files that must be downloaded to build the port.
files/: this directory contains any patches needed for the program to compile and install on FreeBSD. This directory may also contain other files used to build the port.
pkg-descr: provides a more detailed description of the program.
pkg-plist: a list of all the files that will be installed by the port. It also tells the ports system which files to remove upon deinstallation.
NOTE: The port does not include the actual source code, also known as a
distfile. The “extract” portion the build process will automatically download and save the compressed source code in the
To install the port (and clean the directory to remove any temporary files afterward), type
$ make install clean. Notice that a screen similar to the following will show up:
This is a good example of one of the benefits of compiling
irssi from the Ports Collection! It allows you to precisely configure which additional features you want to bundle with the final application binary. Some defaults are already chosen for us, but let’s add “truecolor” support in case we want full bit-depth color when using
irssi in a compatible terminal emulator. Navigate to the option using the arrow keys and press “<Space>”. Once you are satisfied with the configuration, navigate to the “OK” option and press “<Enter>”.
4. Running the application
You now have
irssi installed on your system! Before running it, we’ll do a few things first:
- Exit your root user session by typing
- Ensure that
irssihas been successfully added to your PATH by typing
$ which irssi. The expected output is
To run the application, simply type
$ irssi. You should see a screen like this:
For further information on how to use
irssi, type in
/help in the “status” line. Now you’ll be able to chat with people over IRC!
You did it!
As you can see, compiling and installing an application from the Ports Collection is a satisfying process. However, we just scratched the surface of this process, so for more information, check out the following links:
- https://www.freebsd.org/doc/handbook/ports-using.html for more information on how to update, reconfigure, and uninstall ports. It also describes more advanced processes for further build customization.
- https://www.freebsd.org/doc/en/books/porters-handbook/ for extensive documentation on making your own Ports from scratch!
BONUS: The Ports Collection includes games too! Try using this guide to install
2048, a clone of the popular 2048 game implemented with a command-line interface. This is a great way to explore all the options available for fine-tuning your application build process.