in Code

Point Cloud Library on Mac OS X: A Build Diary

I’ve been using and contributing to various open source projects for almost 20 years. I love the fact that we can leverage each other’s work and help other developers save time instead of reinventing the wheel or fighting the same problem a thousand times over. Open source tools and libraries make what I do possible.  Whenever I use open source, I like to compile from the source so I can contribute back to the projects – even if only little patches for fixing compilation warnings, clarifying error messages, or adding to documentation.  I used to enjoy configuration and build challenges – such as tweaking and compiling my own Linux kernels – but that’s behind me now.  I just want things to work.

I’m a solo developer working on a commercial cross-platform Mac OS X/Windows application.  This means that I have to be careful how I allocate my development time since I also have research to conduct and a business to run.  Part of this is maintaining control of my development “ecosystem”.  The more moving pieces there are – tools, 3rd party libs, etc. – the more overhead, and the less time I have for actual development.  Keeping it simple means saving myself a lot of time.  It also makes it quick and easy to bring short-term contractors on board.

I started to investigate open source tools for processing point clouds for a future version of my software – I want to handle scan data from FARO and Leica scanners.  I quickly zeroed in on the Point Cloud Library which is a BSD-licensed library to read, visualize, manipulate, and process point clouds. It looks like exactly what I need and includes a bunch of capabilities I don’t understand in the least, but seem like they might be useful in the future as I learn about it. Most of the capabilities are too advanced for me to contribute much to them directly, but I thought I’d be able to contribute “around the edges”, so I wanted to build it from source.

Point Cloud Library

Point Cloud Library

This article is a blow-by-blow account of the steps I took while trying to build the Point Cloud Library (PCL) on Mac OS X 10.6 starting with the information from PCL’s Compiling from Source page. The first thing I tried to do is build and link PCL with only the mandatory dependencies. After that, I’ll want to look at the optional pieces and build them if I need them.

As I was working through it, I put together notes for myself on what I did in case I had to do it again or have a contractor do it.  As with most other things I have on this site, I thought at least one other person might benefit through the power of Google, so I decided to put the notes up here verbatim.  Knowing what I know now, I could shorten this dramatically into “Steps to Build PCL on Mac OS X” [even though I haven’t been successful yet], but I decided it might be interesting to show the action-packed sequences of what actually happened…

I hope this is taken in the spirit it’s intended – documentation of some of the problems just getting PCL to configure and build, along with what I hope are some constructive recommendations [at the end of this voluminous tome]. [Warning: I get a little rant-like in the last commentary section – it’s not directed specifically at the PCL, but software development projects in general.]

I have to point out that the PCL guys have been great, answering my initial question quickly, and they’ve been encouraging [so far – hope they still are after this!]. This doesn’t always happen in open source projects, so it’s great to see. They deserve a lot of credit for their work, which is of great value to many  developers and companies worldwide.  All the developers and supporting companies are super-awesome for making this library available as open source. Very much appreciated!

[If you want to skip the gruesome details – don’t forget they’re action-packed! – I list some bugs and recommendations near the end.]

So… here we go!


Download the Sources

Install CMake

  • Downloaded Mac OSX 64/32-bit Universal binary from here.
  • Ran the installer.
  • It asked about installing command line tools [default: /usr/bin].
  • I clicked Install Command Line Links.
  • It gave me an error “Failed create symlink installation may be incomplete: /usr/bin/ccmake” [sic].
  • I realized that it shouldn’t be playing in /usr/bin anyways – it should go in /usr/local/bin – so I adjusted that and it installed.

Aside: For building all these libs I’m using the CMake that was installed.  I don’t use CMake for any projects, so I’m unfamiliar with it.  This will be reflected in my relative cluelessness when using it…

My Setup

On Mac OS X, I keep all my includes, libs, and source code for a project self-contained in one directory – essentially sandboxing my project’s code from the rest of my system. This makes it clear what my dependencies are and what versions I’m using, and lets me update and install current versions of any of the libraries easily. I understand that the way I do things won’t work for everybody – it’s just the way I organize things because it makes sense to me, reduces header/library conflicts with other projects, allows me to use different versions [possibly custom] of the same library easily, and makes it evident what is being used.

So for this test case I have it organized like this:

For any of the libs I build, I will set the prefix to this directory so they will be installed in PCL_Proj/bin, PCL_Proj/include, PCL_Proj/lib, and so on.


Install Boost

  • The PCL Compiling from source page doesn’t specify what parts of boost it uses. I was hoping I could get away with just headers instead of having to compile, so I just copied the boost_1_49_0/boost/ directory into PCL_Proj/include.


Install Eigen

Eigen is just headers and some test programs, so I figured this would be easy.

  1. Ran CMake and pointed at the eigen source.
  2. Chose UNIX makefiles.
  3. For Where to build the binaries I put PCL_Proj/eigen/build.
  4. Clicked Configure, all the options turned red, and I got the following errors:
  5. It looked like all of this is related to test cases and other things, so I ignored them, possibly at my peril!
  6. It also told me: This is not exactly clear to me.
  7. I just wanted to put the headers in my sandbox, so I changed CMAKE_INSTALL_PREFIX to point to PCL_Proj and EIGEN_INCLUDE_INSTALL_DIR to point to PCL_Proj/include.
  8. Clicked Configure again – no longer have a bunch of red options.
  9. Now this message made more sense to me:
  10. Clicked Generate and it built a Makefile.
  11. Used the command line to run make install and it put things in the right place.
  12. I probably could have just copied the headers like I did with Boost, but I wasn’t sure if the install process modified them.


First success!


Build and Install FLANN

  1. Ran CMake and pointed at the FLANN source.
  2. Chose Xcode so it would create a project.
  3. For Where to build the binaries I put PCL_Proj/flann/build.
  4. Clicked Configureand got several errors:
  5. At this point I’m not concerned with the tests, so I ignored HDF5 & GTest errors.
  6. I don’t have CUDA installed [it’s an optional dependency for PCL], so I left it for now.
  7. Turned off BUILD_CUDA_LIB, BUILD_MATLAB_BINDINGS, and BUILD_PYTHON_BINDINGS since I’m not using any of them.
  8. Changed CMAKE_INSTALL_PREFIX to point to PCL_Proj/.
  9. Clicked Configure again – no longer have a bunch of red options.
  10. Clicked Generate and it built an Xcode project.
  11. Opened the project in Xcode, changed the configuration to Release, and built.
  12. While it was building, I took a look at the FLANN manual. It says:

    To make use of FLANN multithreading support, it is required that Intel Threading Building Blocks is installed correctly on your system.

    Huh. Do I want that? Maybe. [Another dependency?!]  Something to consider for the future.

  13. Back in Xcode, changed the target to Install and built.


Success #2!


Build and Install VTK

  1. Ran CMake and pointed at the VTK source.
  2. Chose Xcode so it would create a project.
  3. For Where to build the binaries I put PCL_Proj/VTK/build.
  4. No errors in the output this time!
  5. I want Qt support, so I turned on VTK_USE_QT and ran Configure again.
  6. Changed QT_QMAKE_EXECUTABLE to point to my Qt installation.
  7. Changed CMAKE_INSTALL_PREFIX to point to PCL_Proj/.
  8. Not too sure about the other options, but I turned on the BUILD_EXAMPLES and clicked Configure again.
  9. Clicked Generate and it built an Xcode project.
  10. Open the project in Xcode, changed the configuration to Release, and built.
  11. Changed the target to install and built.
  12. It installed into PCL_Proj/lib/vtk-5.10 and PCL_Proj/include/vtk-5.10.
  13. Tried to run some of the examples, but they crashed with the following error:
  14. Looked up the error using my second brain [Google] and found a potential solution.
  15. In CMake, I toggled the Advanced options, set VTK_REQUIRED_OBJCXX_FLAGS to “”, then clicked Configure, and Generate again.
  16. Opened the project in Xcode, Clean All Targets, built, and installed again.
  17. Now some of the Applications run!


Success #3.


Build and Install PCL

At this point I should have the minimum requirements for building PCL.

  1. Ran CMake and pointed at the PCL source.
  2. Chose Xcode so it would create a project.
  3. For Where to build the binaries I put PCL_Proj/pcl/build.
  4. Clicked Configure.
  5. Gave errors trying to find boost and eigen, so I toggled the Advanced options and changed BOOST_INCLUDEDIR to point to PCL_Proj/include.
  6. Changed CMAKE_INSTALL_PREFIX to point to PCL_Proj/.
  7. Clicked Configure.
  8. Turns out we actually do need some compiled libs from boost…
  9. Went back to build boost again…


Build and Install Boost [Round #2]

  1. Following instructions on building boost.
  2. On the command line, I used: This should install into my sandbox and only build the libs I need.
  3. On the command line
  4. Looks good. Back to PCL…


Build and Install PCL [Round #2]

  1. Back in CMake, add an entry for BOOST_LIBRARYDIR and set to PCL_Proj/lib.
  2. Configure again now that we have Boost libs:
  3. Changed QT_QMAKE_EXECUTABLE to point to my Qt installation.
  4. Configure and Generate.
  5. Opened the project in Xcode, selected Release, and built.
  6. >20000 warnings and 100 errors. Not a terrible start I guess. 🙂
  7. It was failing to build pcl_io because I hadn’t installed the OpenNI lib, but OpenNI should not be required.
  8. Most of the errors were link errors related to OpenMP, so disabled that for now by removing the switches on OpenMP_CXX_FLAGS and OpenMP_C_FLAGS.
  9. In CMake, I turned off BUILD_OPENNI, Configure and Generate. Now my list looked like this:
  10. Noticed that we need another boost lib – boost_mpi – so went back to build boost again.


Build and Install Boost [Round #3]

  1. Use the same command line as last time, but added mpi:
  2. Apparently MPI is special because I got this message:
  3. I figured maybe it’s a cache thing, so I started the boost build from scratch.
  4. Nope – MPI is special.
  5. It doesn’t tell me where user-config.jam is, so on the command line:
  6. Edited user-config.jam, being careful to leave the space before the ‘;’.
  7. Reran and b2 as above.
  8. Looks like that worked, so head back to PCL.


Build and Install PCL [Round #3]

  1. Configure again now that we have boost_mpi:
  2. The glew lib isn’t listed as a PCL dependency, so I ignored that for now to try to build the rest.
  3. Generate Xcode project, opened it in Xcode and attempted a build.
  4. 4 warnings and 315 errors – progress?
  5. Even with BUILD_OPENNI off, pcl_io failed to build because it’s trying to build pcd_grabber.cpp which uses OpenNI.
  6. Most of these were link errors because pcl_io failed to build or it was trying to build tests.
  7. It was trying to build tests even though BUILD_TESTS was off in CMake
  8. pcl_modeler and proctor assume that the Qt build includes STL [i.e. it was not compiled with -no-stl].

So in the end I haven’t been successful at building the PCL libs on Mac OS X [yet]. There are some configuration issues when it’s building the Xcode project that someone will have to fix, or, if I find some time, I’ll have to learn more about CMake to fix them myself. Fortunately, though, it looks like most of the problems so far are just configuration issues.

Of course this is just the download, configure, build phase. After all of this I have to get it linked to something and running…



  1. In PCL CMake, BUILD_OPENNI should be disabled by default if I haven’t installed OpenNI.
  2. pcl_io should build properly with BUILD_OPENNI off.
  3. The CMake-generated project should not try to build any tests if BUILD_TESTS is off.
  4. Changing CMAKE_CXX_COMPILER and CMAKE_C_COMPILER has no effect.
  5. Compilation with OpenMP fails.
  6. pcl_modeler and proctor should be build-able when Qt is compiled with -no-stl.
  7. This may be a fundamental misunderstanding of CMake on my part, but when I see options in red, I figure that means I need to keep clicking Configure until it’s happy. In CMake, if I do not have the Advanced checkbox on, I can miss when I need to reconfigure since things show up in red under Advanced, but they don’t show up on the “basic” screen.


Recommendations For PCL

  1. Add the list of required boost libs [I mean the ones requiring compilation, not the headers] to the Compiling from source page.
  2. If the GTest lib is an optional dependency for testing, it should be included on the Compiling from source page.
  3. If the glew lib is required for pcl_simulation, it should be included on the Compiling from source page.
  4. Add a USE_OPENMP config option
  5. Look at all the config options and see what belongs in Advanced and what doesn’t.  If a user essentially has to have Advanced turned on, what’s the point?
  6. Look at the config options in general to see if they can be simplified and made more consistent/clearer to the user.  e.g. BUILD_OPENNI doesn’t actually mean to build OpenNI, it means to include the optional OpenNI features.  Should probably be named USE_OPENNI or INCLUDE_OPENNI_FEATURES.
  7. Bundle Eigen & FLANN sources with PCL, allowing an override with CMake.
    • Removes some potential sources of link errors [different linking profiles, etc.]
    • Having the default PCL CMake set up to use the bundled sources means two fewer dependencies to manage.
    • Fewer potential configuration problems.
    • Can be certain that the included versions are stable releases and that they compile and work with PCL.
    • Removes at least one tool [mercurial] from the required set of tools.
  8. For the same reasons, consider bundling all required library sources [and even some of the optional ones – Qhull looks like a good candidate] with PCL, license-permitting. As with the Qt example mentioned below this would make it extremely easy for a new developer to download, compile, use, and contribute to the PCL project.
  9. For binary releases, provide a DMG on the Mac and a Zip file on Windows with the following layout:

    • This would provide one download [instead of 9] that includes all headers and libs required to start using PCL.
    • This would allow developers to put the includes and libs where they want them instead of spread throughout /usr, /usr/local, and /opt, [and wherever they’re put on Windows] which is critical if a developer wants to keep these things sandboxed so they don’t interact with other projects they might be working on.


Commentary [though some might call it a rant or even a screed]

There are many different source management, configuration, and build tools being used here, so these become dependencies too since most of them have to be installed and maintained (some on on multiple platforms): svn, git, mercurial, bjam, cmake, make, etc.. When everything works, great! In real life though, things don’t all “just work”. So when any part of this process breaks, a developer has to spend time attempting to track down the problems. Sometimes it’s a misunderstanding of the tool or of an error message. To me, this is a UX bug since in this case the user is another developer. Other times there’s a configuration issue or something that’s not working on a specific platform. This is a major time sink, because there aren’t very many people who are familiar with all the intimate details of each of the previously-mentioned tools.  So if you can’t find a solution using Google, you’re stuck either sinking more time into it, or hoping that someone on the forums will have mercy on you.

Every tool or dependency that’s added to the source management, configuration, and build process increases the barrier to entry for new developers.

I would suggest that a goal of any open source project [not just PCL] should be to reduce this dependency madness and to try to streamline and simplify the configuration and build process. The easier this is, the more developers will try working with the project. Or more accurately, the fewer who will give up after running into issues they can’t solve without having to spend some quality time with Google or learning new tools they’ll only use once.

Developers don’t want to spend time learning new source management, configuration, and build tools. We want to code.

As an example of a massive cross-platform framework that “works”, look at the Qt framework. It is dependent on at least 28 3rd-party libraries, but as a developer that doesn’t really matter to me. To use Qt, I:

  1. Grab the source via git
  2. Determine my configuration options:
  3. Configure it:
  4. Build and install it:

Voila! I’m now up-and-running with Qt. I don’t have to know any details about any of the 3rd party libraries, their special configurations, or their build processes. No chasing libraries down and worrying about version incompatibilities. No time-consuming, iterative – did it work this time? nope, change something and try again – configuration process, where new options “unlock” as you iterate like some terrible game. A UX nightmare!  Qt’s configuration and build process is simple.

I like simple.

Write a Comment



  1. Thanks a lot for taking the time to read this.
    I instal PCL all in one. and i want to configure my project PCL in Qt creator can you send me the step plz

  2. Hello,

    I hope it is ok to treat this place like a forum. I am having a problem with compiling a simple example of a pcl code: pcd_write.cpp

    I am using mac os yosemite 10.10.5. I use CMake. I am getting the following error after I run “make” in build directory.

    Undefined symbols for architecture x86_64: "pcl::PCDWriter::writeASCII(std::__1::basic_string<char, std::__1::char_traits, std::__1::allocator > const&, sensor_msgs::PointCloud2 const&, Eigen::Matrix const&, Eigen::Quaternion const&, int)", referenced from: pcl::PCDWriter::write(std::__1::basic_string<char, std::__1::char_traits, std::__1::allocator > const&, sensor_msgs::PointCloud2 const&, Eigen::Matrix const&, Eigen::Quaternion const&, bool) in pcd_write.cpp.o
    "pcl::PCDWriter::writeBinary(std::__1::basic_string<char, std::__1::char_traits, std::__1::allocator > const&, sensor_msgs::PointCloud2 const&, Eigen::Matrix const&, Eigen::Quaternion const&)", referenced from: pcl::PCDWriter::write(std::__1::basic_string<char, std::__1::char_traits, std::__1::allocator > const&, sensor_msgs::PointCloud2 const&, Eigen::Matrix const&, Eigen::Quaternion const&, bool) in pcd_write.cpp.o
    ld: symbol(s) not found for architecture x86_64 clang: error: linker command failed with exit code 1 (use -v to see invocation) make[2]: *** [pcd_write_test] Error 1 make[1]: *** [CMakeFiles/pcd_write_test.dir/all] Error 2 make: *** [all] Error 2

    In one of the posts, they suggest to set the -stdlib to libstdc++.
    I did that and the error disappeared. But this time this error appeared:

    /opt/local/include/eigen3/Eigen/src/Core/util/Memory.h:713:23: error: no member named 'forward' in namespace 'std' ::new(p) T(std::forward(args)...);
    /opt/local/include/eigen3/Eigen/src/Core/util/Memory.h:713:31: error: 'Args' does not refer to a value ::new(p) T(std::forward(args)...);
    /opt/local/include/eigen3/Eigen/src/Core/util/Memory.h:710:26: note: declared here template

    According to what I read in other posts, this happens because clang requires libc++ to link std::.
    I saw one blog that suggests to rebuild every library again using libstdc++. I don’t want to broke something that is already working by doing that. Have you ever had such a problem?
    Thank you,

  3. I just stumbled upon this post and thought I add my own experiences, since I have been using PCL for more than a year under Mac OS X.

    First, I would like to say that your comparison with Qt is not fair, as you are talking about building PCL in Xcode, while you use configure/make to build Qt. My point is, that PCL actually builds very well under Mac OS X, when you leave Xcode out of the picture and use ccmake/make (Try building Qt with Xcode and you may have very similar issues). Yes, PCL has some dependencies, but it’s actually quite manageable. I use homebrew to get those, which provides fairly good Mac OS X integration.

    Second, I do agree that CMake and its capability of generating Xcode projects probably needs work. Personally, I am linking with PCL in my CMake project under Mac OS X every day, but never got that to work with Xcode. Lucky for us, you don’t need Xcode to build your code and can simply use the command line tools provided by Apple or – once again – use homebrew to get the latest gcc compilers.

    Lastly, I would very much like to see how I can link my code with PCL in XCode, so if anyone has managed to do so and found some secret CMake properties that need to be set, please share what you found. My current issue is documented here:

    • Chris:

      Thank you very much for taking the time to comment.

      In my defense, the last part – the commentary – is a general comment on open source – I’m not specifically trying to compare PCL and Qt, cmake and XCode. What I was trying to point out is that Qt includes all its lib dependencies. I don’t need to track down all the libs or several more build/config/scm tools to get it to work. Batteries included.

      When you talk of PCL dependencies being “manageable”, well, that’s really going to depend on your project and the rest of your workload. What I’m arguing is that the more obstacles you put in front of developers, the fewer developers are going to want to try and work with it. (I, for one, no longer enjoy learning the latest, greatest build/config/scm tools. Must be getting old.)

      Since I wrote this article, I’ve ditched XCode in favour of Qt Creator. I still won’t use cmake for my own projects, but I do use it on the command line now for other libs (see more recent post on compiling OpenCV).

      As I pointed out in an earlier comment, I never got far enough to start using PCL in my own code. When I wrote this article, I’d decided that it was too complex a build process and that it would be too much for a one-dev shop to maintain (though I imagine they’ve improved things at least a bit by now). So I’m afraid I don’t have any insight to help with your link issue.

      I wish you luck with your project and thank you again for stopping by!

  4. Hello,

    After compiling successfully PCL library, I am having trouble when adding it to a Xcode project.
    Same as here:
    Do you have an idea on how to solve this problem?

    Also I saw from that you were generating xcode project using cmake. Can you help me telling what is the command for that? Maybe using this method and then looking at the generated Xcode project settings could help me understand how to solve my problem.


    • Meach:

      Do you have an idea on how to solve this problem?

      I never got far enough to start using PCL in my own code. I decided it was too complex a build process and that it would be too much to maintain for a one-dev shop.

      Without the project it’s kind of hard to debug, but the PCL lib does have headers named time.h which is just a terrible idea all around, so it’s not too surprising there would be an issue.

      I would start by looking at the order your headers are being included and what the namespaces look like. It’s likely when trying to include the system time.h you’re getting the PCL one which would result in an error like that.

      Aside: A standard practice I use is to order my includes at the top of the file from system to frameworks to 3rd party libs and finally my project ones. This can avoid some of these types of problems.

      #include <math.h>

      #include <QVarLengthArray>

      #include "flann/flann.h"

      #include "myProjectHeader.h"

      Also I saw from that you were generating xcode project using cmake. Can you help me telling what is the command for that?

      To generate an Xcode project in CMake, I just chose the source code location and a location for the build at the top, and when I clicked Configure a wizard popped up. First it asks about creating the missing dir and then the next step asks what generator to use. I selected Xcode.

      I know the PCL devs have done work on the Mac side of things since I looked at at. Hopefully it’s better than when I looked at it last year!

      Good luck with your project!

  5. The headache you describe above is similar to the experience in Windows. An additional problem in Windows is that occasionally some of the headers and library files or even a whole include directory is missing after a “successful” build and installation, leading to some of the tutorial code not working. I wholeheartedly agree with your recommendations. Thanks for sharing your experience for the benefit of others.


    P.S.- Having wrestled with CMake considerably myself, I can tell you that the red highlighting does not indicate a problem necessarily, but rather something that has been added or modified. So actually it can indicate success if you were trying to add something.

    • jmanring:

      Thanks a lot for the comment and for taking the time to read this.

      If it’s going to remain this tough to manage, and it’s the same on Windows, I’ll either have to try the binaries, leaving me at the mercy of others to fix problems and build releases, or try to find a simpler solution.

      CMake: I’ve tried other projects using CMake, but always given up. As someone who appreciates design and usability, I find CMake incredibly frustrating with its iterative approach and hidden options. I guess I just don’t get the mindset and it… wait… red means success?!?