LXDE:PCManFM build and setup guide

From LXDE.org
Jump to: navigation, search

Since 2010, PCManFM has undergone a complete rewrite from scratch. So the new PCManFM is totally different from the old (legacy) 0.5.x series. Build instructions, the ways to setup and configuration files are different too. Here are complete build instructions and a setup guide.

Packages on different distros have a totally different naming, so only the generic names are listed here. Regarding to how those packages are named in your distro, it's distro-dependent and please refer to your own distros.

General build notes

On some distros you already have latest GIT sources with debug info built for you, on some other distros you can build fresh sources into packages respecting distro package system. Package respecting build should be always preferred to manually built and installed files because if similar files coexist in your system they may not always work correctly - for example, build pcmanfm against not system-default libfm but against libfm that is installed onto custom path may be very tricky in many cases. See some distro-specific notes below.


You may find fresh binary packages and source packages at Lubuntu Developers Team PPA. Just add the PPA to your APT list following instructions on that page and you can upgrade your current libfm and pcmanfm to newer versions.

If you wish to create and install own packages then you should do steps:

  • get LibFM source code from PPA
apt-get source libfm
  • go to directory with downloaded and unpacked code
  • install prerequisite packages
sudo mk-build-deps -i -r
  • build packages
  • return to upper directory
  • install built packages
sudo dpkg -i libfm-*.deb
  • get PCManFM source code from PPA
apt-get source pcmanfm
  • go to directory with downloaded and unpacked code
  • build packages
  • return to upper directory
  • install built packages
sudo dpkg -i pcmanfm-*.deb

Of course, you can update source tree from GIT using instructions below and even apply own patches to test something.

If you decide to revert back to system-default packages you can do that in package manager user interface program such as aptitude.

Arch Linux

You can build and install fresh PCManFM using AUR package pcmanfm-git. To build it with debug info you should add debug into PKGBUILD options:


Build Prerequisite

Build time Dependencies

  • GTK+ 2 >= version 2.18
  • Glib >= version 2.22
  • Cairo >= version 1.8
  • menu-cache >= version 0.3.2 (This is a small lib from LXDE project. Used for application menu integration)
  • Libtool
  • Pkg-config

Note: Libfm version 1.0 have a bit higher requirements. That was fixed in version 1.0.1.

Additional Dependencies

If you're building source code from git repository rather than released tarballs, you'll need these:

  • automake >= 1.11
  • autoconf >= 2.63
  • intltool >= 0.40
  • gettext

Get the Source Code

Released tarballs

Tarballs are not current - for current build get sources from GIT

The latest source code in development from git

To get source code from git repository, use this command (If this gives you an error (timeout) just keep trying and it will work):

cd /usr/src
git clone <repository URL>

(/usr/src is given as an example and you can use whatever directory you like)

Compile the Source Code

If you have any of mentioned components already installed in your system, either manually or by your distribution's package manager, then doing this will overwrite your existing files!

After installing the prerequisites, compiling should be smooth.

Additional step for git

configure script is only provided in tarballs. For source code downloaded from git repo, you need to generated them manually with autogen.sh after installing dependencies (also see below).

cd /usr/src/menu-cache

Do the same for each component. If you get errors then you haven't installed all dependencies correctly

Compile and Install - Linux Ubuntu or Debian

Install all required dependencies:

sudo apt-get install dpkg-dev autoconf automake autotools-dev intltool libglib2.0-dev libgtk2.0-dev libmenu-cache1-dev libtool pkg-config

If you're compiling version 1.0 from git sources then you should have package valac at least version 0.13.0 installed too. (note: version of 1.0.1 contains a bug that requires valac even on compilation from tarball)

Libfm newer than 1.0 can be compiled even if such package isn't available with cost of disabling custom actions support. Check if you have valac at least 0.13.0 installed. Run:

dpkg -l valac

and look into output if it contains line like this:

ii  valac             0.14.0-0ubuntu1   C# like language for the GObject system

The text 0.14.0-0ubuntu1 in example above is a version of valac package.

Compile and install components:

  • libfm:
    • if you have valac >= 0.13 available
cd /usr/src/libfm
./configure --prefix=/usr && make
DEB_MULTIARCH=`dpkg-architecture -qDEB_HOST_MULTIARCH 2>/dev/null` && rm -f /usr/lib/$DEB_MULTIARCH/libfm-*
sudo make install-strip
    • without valac
cd /usr/src/libfm
./configure --prefix=/usr --disable-actions && make
DEB_MULTIARCH=`dpkg-architecture -qDEB_HOST_MULTIARCH 2>/dev/null` && rm -f /usr/lib/$DEB_MULTIARCH/libfm-*
sudo make install-strip
  • pcmanfm:
cd /usr/src/pcmanfm
./configure --prefix=/usr && make
sudo make install-strip

Compile and Install - FEDORA

Install all required dependencies using the yum-builddep command (part of the yum-utils package).

su -c 'yum-buildep menu-cache'
Please make sure to export the proper library path depending on your architecture!

  • For 32 bit
export libdir=/usr/lib
  • For 64 bit
export libdir=/usr/lib64
  • menu-cache:
cd /usr/src/menu-cache 
./configure --prefix=/usr --libdir=$libdir && make
make install-strip
  • libfm
cd /usr/src/libfm
./configure --sysconfdir=/etc --prefix=/usr --libdir=$libdir && make
make install-strip
  • pcmanfm
cd /usr/src/pcmanfm
./configure --sysconfdir=/etc --prefix=/usr --libdir=$libdir PKG_CONFIG_PATH=$libdir/pkgconfig/ && make
make install-strip

Compile and Install - FreeBSD

By default binary and data are installed under /usr/local and that is the default location for FreeBSD packages. Only exception is the pkg-config related files, they are installed into /usr/local/libdata/pkgconfig. And also you have to use GNU make instead of BSD make (currently BSD make is not supported). Therefore installation is simple enough:

  • menu-cache:
./configure && gmake
sudo gmake 'pkgconfigdir=/usr/local/libdata/pkgconfig' install-strip
  • libfm
./configure && gmake
sudo gmake 'pkgconfigdir=/usr/local/libdata/pkgconfig' install-strip
  • pcmanfm
./configure && gmake
sudo gmake install-strip

Compile and Install - Other

By default, programs will be installed to /usr/local. If you want to change the location, for example /usr, pass --prefix=<the dir you want> to "configure".

  • menu-cache:
./configure && make
sudo make install-strip
  • libfm
./configure --sysconfdir=/etc && make
sudo make install-strip
  • pcmanfm
./configure && make
sudo make install-strip

Please note that --sysconfdir=/etc is needed if you want to install config files under /etc. Otherwise default config files will be installed to /usr/local/etc.

Install and use local version of the packages

In some cases you might desire to test some local version of menu-cache, libfm, and pcmanfm, and keep system-wide data intact. That can be easily done as well. All you need to do is to set compiling and runtime environment appropriately, and also set installation paths as well. This way you even can test versions that are totally different from those you have on your system. See an example below, this example assumes your files should be installed below $HOME/testing directory.

  • menu-cache:
./configure --prefix=$HOME/testing
make && make install
  • libfm
PKG_CONFIG_PATH=$HOME/testing/lib/pkgconfig ./configure --prefix=$HOME/testing
make && make install
  • pcmanfm
PKG_CONFIG_PATH=$HOME/testing/lib/pkgconfig ./configure --prefix=$HOME/testing
make && make install

To start this compiled binary you should set LD_LIBRARY_PATH, for example from above it can be done if you run pcmanfm this way:

LD_LIBRARY_PATH=$HOME/testing/lib $HOME/testing/bin/pcmanfm

Setup Runtime Environment Correctly

Runtime Dependencies

  • GTK+ >= version 2.18
  • Glib >= version 2.22
  • menu-cache >= version 0.3.2
  • lxmenu-data (data files for application menu integration)
  • gamin or other FAM backend (not required for Glib 2.27.1 or newer)
  • gvfs and its dependencies (optional, but highly recommended):
    • dbus and dbus-glib (required by gvfs)
    • policykit-gnome (required for authentication for volume management)
    • Other dependencies of gvfs are all optional. That depends what configure options are turned on when compiling gvfs. If packager of your distro includes all options and didn't try to split the packages (Ubuntu, for example), you'll get a lot of dependencies. However those dependencies are not mandatory. If you carefully choose configure options or splitting the package in a more sensible way, those dependencies are all optional and can be make minimal. Bug report to your distro if you find there are a lot of unwanted dependencies caused by gvfs since they should have been optional.

Other requirements

If you want to make use of gvfs support, here are some requirements.

  • Dbus should be launched correctly
    • If you're using Gnome, XFCE, or LXDE, you don't need to touch this.
    • Try 'env | grep DBUS', if you see nothing from the output, your dbus is not running and you need to launch it.
    • man dbus-launch to see how to use it. The most easy way is adding this to your .xinitrc or whatever startup script your WM uses.
## test for an existing bus daemon, just to be safe
if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
    ## if not found, launch a new one
    eval 'dbus-launch --sh-syntax --exit-with-session'
    echo "D-Bus per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS"
  • Policykit authentication agent needs to be running (policykit-gnome)
    • If you want to launch it in your startup script:
    • If you're using LXDE or something that supports freedesktop.org autostart spec:
mkdir -p ~/.config/autostart
cp /etc/xdg/autostart/polkit-gnome-authentication-agent-1.desktop ~/.config/autostart

Then, edit ~/.config/autostart/polkit-gnome-authentication-agent-1.desktop and remove this line:


Actually this program is not Gnome only, but this line disable it deliberately in desktops other than Gnome or XFCE.

Without those two, gvfs won't work correctly.

To turn off GVFS support

  • Remove gvfs (This should always work)
  • Or, here is a more elegant way. This works even if you have gvfs installed
export GIO_USE_VFS="local"

Using PCManFM with GLib older than 2.27.1

  • New feature of Libfm to support custom actions in context file menu cannot work with GLib older than version 2.26 so to compile it you have to disable actions by supplying option --disable-actions for configure script.
  • If you are using PCManFM with GLib older than 2.27.1 you may get bad effect: PCManFM does not update content of directory when you create file in it or delete file from it. That bug may happen if you installed GLib without modules so to fix it install all GLib modules, please.

Command line options


 pcmanfm [OPTION...] [FILE1, FILE2,...] 

Help Options:

 -h, --help                           Show help options
 --help-all                           Show all help options
 --help-gtk                           Show GTK+ Options

GTK+ Options

 --class=CLASS                        Program class as used by the window manager
 --name=NAME                          Program name as used by the window manager
 --screen=SCREEN                      X screen to use
 --sync                               Make X calls synchronous
 --gtk-module=MODULES                 Load additional GTK+ modules
 --g-fatal-warnings                   Make all warnings fatal

Application Options:

 -p, --profile=PROFILE                Name of configuration profile
 -d, --daemon-mode                    Run PCManFM as a daemon
 --no-desktop                         No function. Just to be compatible with nautilus
 --desktop                            Launch desktop manager
 --desktop-off                        Turn off desktop manager if it's running
 --desktop-pref                       Open desktop preference dialog
 -w, --set-wallpaper=FILE             Set desktop wallpaper from image FILE
 --wallpaper-mode=MODE                Set mode of desktop wallpaper. MODE=(color|stretch|fit|center|tile)
 --show-pref=N                        Open Preferences dialog on the page N
 -n, --new-win                        Open new window
 --role=ROLE                          Window role for usage by window manager
 --display=DISPLAY                    X display to use

Bug Reporting and How to Help Debug PCManFM

We really need your help to make it better. If you find crashes, here are the instructions how you can help us track it down.


  • Turning on debugging options with --enable-debug will make pcmanfm slightly slower, but this helps debugging a lot. For production use, don't turn this on.

Steps to help debug pcmanfm:

  • Install gdb
  • Compile libfm and pcmanfm with debugging support by adding --enable-debug to options (this is just an example, refer to instructions for your distribution above):
./configure --enable-debug --prefix=/usr
make clean install

(note install not install-strip since install-strip will remove debug info which we need)

  • Kill all running instances of pcmanfm:
 killall pcmanfm
  • Export some glib environment variables to help debugging. These environment variables turn on additional debugging facilities built-into glib and very often can greatly help debugging:
export G_DEBUG=fatal-criticals
export G_SLICE=debug-blocks
  • Run pcmanfm with gdb:
gdb pcmanfm 
  • Then, in gdb, type 'run' (you can add usual command-line arguments such as --desktop to 'run'):
(gdb) run
  • When you get a crash, type 'thread apply all backtrace full' in gdb to get backtrace data of all threads:
(gdb) thread apply all bt full
  • If your problem is not a crash but pcmanfm hangs then to trace the problem you have to press <Ctrl>+<C> and you'll get the gdb prompt so you can enter the same command as above to get backtrace data.
  • Send the backtrace along with your bug report to us. Nice backtrace can greatly help us track down the bugs. Without gdb backtrace, a bug report containing 'pcmanfm crashes sometimes.' only doesn't help at all and would be ignored by developers since it contains no useful information.
  • What a good useful bug report should contain:
    • Your distro OS version
    • Version of libfm and pcmanfm you are using
    • How to reproduce the bug (exact steps)
    • The gdb backtrace
  • Send the bug report to bug tracker rather than mail it to the authors directly.

Priority of bug reports

Since it's not possible to fix all of the bugs at the same time, the bug reports have to be prioritized. Here are the rules used to prioritize them:

  • Priorities 1 to 3 - minor bugs (on optional actions or features):
1 - badly documented;
2 - lesser feature not always works;
3 - some additional functionality required.
  • Priorities 4 to 6 - major bugs (on main actions such as windows, drag&drop, etc.):
4 - action sometimes does not work;
5 - action works not way it intended to;
6 - action does not work at all or breaks something else;
  • Priorities 7 to 9 - critical bugs:
7 - crash in some conditions;
8 - frequent crash, hangup, program fails to start in some conditions;
9 - program fails, hangs or crashes on start.

Additional Info for Packagers

You can customize the default configuration of libfm and pcmanfm. The default config files are installed to /etc/xdg/libfm and /etc/xdg/pcmanfm. You may do your customization to /etc/xdg/libfm/libfm.conf and /etc/xdg/pcmanfm/pcmanfm.conf. If you don't know what options are supported, use ~/.config/pcmanfm/pcmanfm.conf as a template. Take into consideration that those files are used only if user's config file is missing. Besides, pcmanfm supports using different profile. pcmanfm --profile=lxde for example let you use lxde.conf instead of pcmanfm.conf. So, you can do pcmanfm --profile <your_custom_config_file> in your startup script and then there is no need to patch the package itself.