How do I run the dynamically linked version of Stata on Linux?

Stata for Unix now uses GTK+-2.0 to create its graphical user interface. Although most distributions of Linux have included GTK+-2.0 dynamic libraries for some time, Stata may use some features of GTK+-2.0 that may be unavailable in the version of GTK+-2.0 currently installed on your computer. For this reason, we recommend that you use the statically linked versions of Stata for Linux.

We do, however, include dynamically linked versions of Stata for Linux. The following document describes the minimum set of libraries you will need to run the dynamically linked version of Stata for Unix, as well as how to build and install them.

Before you start

Why would you want to run the dynamically linked version of Stata?

A dynamically linked version of any executable will have a smaller footprint for both memory and disk space. Newer versions of dynamic libraries with bug fixes and performance improvements to GTK+-2.0 that a dynamically linked executable will pick up may be available. Also only a dynamically linked version can supports themes from GNOME desktop.

I’m getting messages like “error while loading shared libraries:” followed by a list of missing libraries. What does that mean?

You are attempting to run the dynamically linked version of Stata, but your system does not have the required libraries. You must either install the statically linked version of Stata or install a version of the GTK+-2.0 libraries that is compatible with Stata.

How do I tell if my GTK+-2.0 libraries are compatible with Stata?

Install the dynamically linked version of Stata appropriate for your license and try to launch it, or use ldd on the executable for a list of dependencies. If Stata launches or ldd reports no missing dependencies, then you will not need to do anything else. Otherwise, you can upgrade the libraries by installing RPMs or by compiling and installing the libraries yourself.

What do I need to install the GTK+-2.0 dynamic libraries?

Besides RPMs or source code, you will probably need superuser access if you are making a systemwide installation.

Install with RPMs or compile and install?

If you can, use RPMs to upgrade your GTK+-2.0 libraries. Stata’s minimum requirement for GTK+-2.0 is GTK+ 2.8.17, GLIB 2.10.2, Cairo 1.4.2, GtkSourceView 1.6.0, and their dependencies. Having the most recent version of Cairo is important because earlier versions of Cairo can have trouble drawing Stata graphs with complex paths.

If RPMs are not available for your Linux distribution, proceed to the Compiling and installing GTK+-2.0 step.

Installing RPMs

Depending on your Linux distribution, you probably have a package manager that can resolve any dependencies and download the latest library versions available for your operating system. Newer versions of Red Hat and Fedora use yum, Suse has yast, Debian and Ubuntu use apt, and Gentoo uses the portage system. You will need to consult your distribution’s manual pages for package installation syntax.

You can also visit public repositories and manually download the necessary files. Sites such as freshrpms.net and rpmfind.net have many updated packages for most mainstream Linux distributions.

Compiling and installing GTK+-2.0

Before you download, compile, and install the libraries, you must set up your build environment. For bash, use

export LD_LIBRARY_PATH="/usr/local/lib"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig"
export PATH="/usr/local/bin:$PATH"

For csh, use

setenv LD_LIBRARY_PATH "/usr/local/lib"
setenv PKG_CONFIG_PATH "/usr/local/lib/pkgconfig"
setenv PATH "/usr/local/bin:$PATH"

The default installation directory for the libraries is /usr/local. The actual dynamic libraries will be installed in the subdirectory lib of the installation directory (here, /usr/local/lib). If you plan on installing the libraries and their subdirectories elsewhere, make sure that you specify where the actual libraries and pkg-config files will be installed in the package’s configure step.

Download the source code archives listed in the Minimum set of libraries column of the following table. This is the minimum set of libraries you will need if your Linux distribution has libraries older than those required to run Stata.

Download the source code archives listed as Possible dependencies only if you have an older Linux distribution that does not have GTK+-2.0 installed at all or if building the minimum set of libraries fails because of missing dependencies. Not all libraries may have to be built, and the archive links are provided only to resolve any possible missing dependencies.

Your Linux distribution must have pkg-config installed. We recommend using gcc for compiling the libraries.

Once the minimum set of libraries’ archives are downloaded, you must compile and install each library in the order listed because some packages will require others to build properly. It is best to extract the source code for a library, and then compile and install it before extracting the next library. This approach will help you keep track of the build process and aid in dependency resolution.

It is possible that only a few libraries do not meet the minimum requirement for Stata. If that is the case, only compile the libraries that are listed in the "error while loading shared libraries:" message. For example, if after launching Stata, you receive a message that there was an error loading the shared library libtiff.3.7.4.so, then only compile the library for TIFF-3.7.4. Repeat until all dependencies are resolved.

Usually, you need to perform only the following steps (after extracting a library’s source code and changing to the extracted directory).

$ ./configure
$ make
$ sudo make install

If you need to set any environment variables for compilation, do it at the configure step. For example,

$ env CC=gcc CFLAGS=-m64 ./configure

We only provide the -m64 compiler flag to the configure script as an example. gcc will generate code native to the environment (32 bit or 64 bit) when the -m is not specified.

Configuring the Fontconfig library involves a couple of extra steps. If you already have Fontconfig installed, you should backup your existing font configuration file /etc/fonts/fonts.conf. Do not backup the file as /etc/fonts/fonts.conf.bak as the Fontconfig installation script will do that for you, and there's a danger of losing your original configuration file if it takes you multiple attempts to install Fontconfig.

Use the command ./configure --sysconfdir=/etc to configure Fontconfig. After you install Fontconfig, the install script will replace your original font configuration file with a new one. Copy the original fonts.conf back to /etc/fonts/fonts.conf.

$ cp /etc/fonts/fonts.conf ~/fonts.conf.orig
$ ./configure --sysconfdir=/etc
$ make
$ sudo make install
$ sudo cp ~/fonts.conf.orig /etc/fonts/fonts.conf

If Fontconfig is not already installed on your system, it is not necessary to specify the --sysconfdir flag.

The default installation directory for libraries is /usr/local. All appropriate directories needed by the libraries (lib/, etc/, bin/, etc.) will be installed there. if you wish to install the libraries elsewhere, use the --prefix option with configure. For example, to install the libraries into /opt/freeware, enter

$ ./configure --prefix=/opt/freeware

We strongly recommend that you do not set the installation directory to /usr. If you are unsuccessful in installing any of the libraries and their possible dependencies, you may leave your system in an unstable state.

If a library depends on a library that is not available on your system (unlikely), then the configure script will fail and notify you of the dependency. Before proceeding any further, you must resolve the dependency before compiling and installing the library.

After installing the libraries, you can confirm a successful build by launching the gtk-demo executable from the bin/ subdirectory of your installation directory (typically /usr/local/bin/). If it does not run, then you did not properly compile and install the libraries. If it does run and you are sure that you are running a freshly built gtk-demo and not one that may already exist in /usr/bin, then you can install the dynamically linked version of Stata and run it.

Troubleshooting

If Stata does not launch, make sure the environment variable LD_LIBRARY_PATH points to the path of the newly installed libraries:

$ export LD_LIBRARY_PATH "/usr/local/lib"

If Stata still does not launch on a 64-bit machine, type

$ file /usr/local/bin/gtk-demo

to verify that gtk-demo is a 64-bit executable. If it is not, then you built 32-bit versions of the libraries and must recompile the entire GTK+-2.0 environment.

Unfortunately, in-depth troubleshooting of any problems during the compiling and installing step is beyond the scope of this FAQ and Stata technical support. Search the web for help in troubleshooting your problems. If resolution is not possible, then you should revert to the statically linked version of Stata.