= Mac OS X Installation using Homebrew Instructions (10.6 or later) =

<<TableOfContents(4)>>

== SVN Based Install (download-and-compile) ==

=== Install Xcode 4 ===

Xcode 4 can be installed from the App Store in Lion, it is a free, but it is a large download. It is required before moving forward.

http://developer.apple.com/technologies/tools/

=== Install Homebrew ===

First install [[http://mxcl.github.com/homebrew/|Homebrew]] by running this script in the terminal:

 ~-{{{
ruby -e "$(curl -fsSkL raw.github.com/mxcl/homebrew/go)"
}}}-~

'''(Optional)''' Change the permissions of your Python, Ruby, and Perl library directories to prevent the need for `sudo` when running `pip`.  This is recommended by the Homebrew developers, but not strictly necessary.

 ~-{{{
sudo chown -R $USER /Library/Ruby /Library/Perl /Library/Python
}}}-~

'''Note:''' If you chose to do the above add this line to your `~/.bashrc` file: `export ROS_NO_SUDO_PIP=True`.

=== Environment Setup for Homebrew ===

Add the following lines to your `~/.bashrc` file in order to prepare your environment for use each time you open a terminal:

 ~-{{{
export CPLUS_INCLUDE_PATH="/usr/local/include:$CPLUS_INCLUDE_PATH"
export PYTHONPATH="/usr/local/lib/python2.7/site-packages:/usr/local/lib/python:$PYTHONPATH"
export ROS_OS_OVERRIDE=osxbrew:lion
}}}-~

The first line prepends the include directory used by Homebrew so that you can find the headers of Homebrew packages.  The second line prepends the default directory for Homebrew-installed Python libraries to the Python path so Python can find them.  The third line lets [[rosdep]] know that we want to use Homebrew for package resolution.

Execute this line to have these changes take effect:

 ~-{{{
. ~/.bashrc
}}}-~

=== Install Necessary Dependencies ===

Install `cmake`, `autoconf`, `automake`, `autogen` and `libtool` for build systems, `wget` for fetching files, and `libyaml` for reading configuration files:

 ~-{{{
brew install wget cmake autoconf automake autogen libtool libyaml --universal
}}}-~

Install `pip`, which is a package manager for Python, using `easy_install`: 

 ~-{{{
sudo easy_install pip
}}}-~

Install Mercurial, which is a version control system, and !PyYaml, which is a python interface to libyaml:

 ~-{{{
sudo pip install mercurial pyyaml
}}}-~

'''Note:''' If you opt'ed into the permission changes above in the instructions, you will not need to prepend each of the above easy_install and pip statements with `sudo`.

=== Add Homebrew-Specific rosdep Entries ===

There are still several packages lacking proper Homebrew `rosdep` entries, which define how to resolve dependencies using Homebrew.  Run this command to add them to your `rosdep.yaml` override file, adding the definitions globally:

 ~-{{{
mkdir -p ~/.ros/
wget http://kforge.ros.org/rososx/homebrew/raw-file/tip/electric/rosdep.yaml -O ~/.ros/rosdep.yaml
}}}-~

<<Include(electric/Installation/rosinstall)>>

== Notes About Installing with Hombrew ==

There a few things that developers should know about using Homebrew.  

=== Pip is used for Python Packages ===

Homebrew only provides packages that do not ship with OS X or Python packages that cannot be installed via `pip`.  Therefore in addition to Homebrew installing things to `/usr/local/`, this ROS setup leverages `easy_install` and `pip` from the system Python provided by Apple to install Python package dependencies.

=== Macports Conflicts with Homebrew ===

Additionally, Homebrew is known to have conflicts with Macports.  If you are using Macports and want to try out the ROS with Homebrew setup, I recommend temporarily moving the Macports folder to prevent conflicting libraries:

 ~-{{{
sudo mv /opt/local /opt/_local
}}}-~

To restore Macports at a later date simply rename the folder back to the original name.

=== wxPython and wxWidgets are installed from a Binary ===

Because of difficulties in reproducing a wxPython/wxWidgets build that is cocoa compliant, a development binary installer is used.  This installer is downloaded and run automatically for you by rosdep, but you will be prompted for sudo credentials, so if you just `rosmake --rosdep-install rviz` keep an eye out for `rosdep` asking for your password.

=== nVidia CG toolkit is Installed from a Binary ===

In addition to wxPython, nVidia's CG toolkit is installed from a binary.  It will also install automatically and prompt you for sudo credentials.

=== rosconsole may need an additional patch ===

In case rosconsole fails to build because of a "g++-4.2 not found" error, use the patch found here: https://code.ros.org/trac/ros/changeset/15411

=== Cairo may have to be built using clang ===

In case Homebrew fails to build Cairo, use the following command:
{{{
brew install cairo --use-clang
}}}

=== in case OGRE refuses to built ===

If pbxcp is missing, this is mostly because it was moved to a new location in XCode 4.3, see [[http://answers.ros.org/question/32516/ogre-on-osx-with-xcode-432-pbxcp-error/|answer.ros.org]] for a fix.

In case OGRE refuses to build with the error "BUILD FAILED: Plugin_CgProgramManager.so not created.  Is nvidia-cg-toolkit installed?", this fix is known to work:
{{{
( cd visualization_common/ogre ; rm installed_osx ; make )
}}}

== Troubleshooting ==

=== Unsigned Certificate (or hang at first `rosinstall`) ===

You might get this error the first time you run `rosinstall`:

{{{
∫ rosinstall ~/ros "http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=desktop-full&overlay=no"
rosinstall operating on /Users/someuser/ros from specifications in rosinstall files  /Users/someuser/ros/.rosinstall, http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=desktop-full&overlay=no
Installing https://code.ros.org/svn/ros/stacks/ros/tags/ros-1.6.5  to /Users/someuser/ros/ros
Error validating server certificate for 'https://code.ros.org:443':
 - The certificate is not issued by a trusted authority. Use the
   fingerprint to validate the certificate manually!
Certificate information:
 - Hostname: *.ros.org
 - Valid: from Thu, 10 Sep 2009 23:16:35 GMT until Wed, 12 Sep 2012 05:05:53 GMT
 - Issuer: Equifax Secure Certificate Authority, Equifax, US
 - Fingerprint: fb:45:70:74:bf:12:94:01:05:23:8d:ee:b2:04
(R)eject, accept (t)emporarily or accept (p)ermanently?
}}}

Visit https://code.ros.org/ in your web browser, pull up the certificate information, and verify the fingerprint in your browser matches the one shown by `rosinstall` (or `svn co`).  If it does, simply accept it permanently, by pressing `'p'` and `'enter'`, to solve the problem.

This may also manifest as a hang during your first `rosinstall` invocation:

{{{
rosinstall operating on /Users/someuser/ros from specifications in rosinstall files  http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=desktop-full&overlay=no
(Over-)Writing /Users/someuser/ros/.rosinstall
[ros] Installing https://code.ros.org/svn/ros/stacks/ros/tags/ros-1.6.8 (None) to /Users/someuser/ros/ros
}}}

Hit ^C to abort the installation, and try running `svn co` by hand using the URL in the output above:

{{{
svn co https://code.ros.org/svn/ros/stacks/ros/tags/ros-1.6.8 ~/ros/ros
}}}

You should then get the same certificate error and prompt above, and you can resolve it as discussed there.

=== Log4cxx Installation Hangs ===

There have been reports that during the make install step of installing log4cxx the process will hang.  You can sometimes tell this has happened when the cpu usage stays low for a long time during the make install step of log4cxx. This might have to do with the automated install of java when building log4cxx on a "clean" OS X install.

To remedy this simply cancel the process with `ctrl-c` and then rerun the previous command.  It should install successfully the second time through.  If it is does not ask a question on [[http://answers.ros.org/questions/]].

=== `rosconsole` Fails with no g++-4.2 ===

If you get this error when building rosconsole:

{{{
mkdir -p bin
cd build && cmake -Wdev -DCMAKE_TOOLCHAIN_FILE=`rospack find rosbuild`/rostoolchain.cmake  ..
[rosbuild] Building package rosconsole
[rosbuild] Including /Users/william/ros/ros_comm/clients/roslisp/cmake/roslisp.cmake
[rosbuild] Including /Users/william/ros/ros_comm/clients/rospy/cmake/rospy.cmake
[rosbuild] Including /Users/william/ros/ros_comm/clients/cpp/roscpp/cmake/roscpp.cmake
-- Configuring done
-- Generating done
CMake Warning:
  Manually-specified variables were not used by the project:

    CMAKE_TOOLCHAIN_FILE


-- Build files have been written to: /Users/william/ros/ros_comm/tools/rosconsole/build
cd build && make 
[  0%] Built target rospack_genmsg_libexe
[  0%] Built target rosbuild_precompile
[ 50%] Building CXX object CMakeFiles/rosconsole.dir/src/rosconsole/rosconsole.o
make[3]: /usr/bin/g++-4.2: No such file or directory
make[3]: *** [CMakeFiles/rosconsole.dir/src/rosconsole/rosconsole.o] Error 1
make[2]: *** [CMakeFiles/rosconsole.dir/all] Error 2
make[1]: *** [all] Error 2
make: *** [all] Error 2
}}}

Apply this patch: https://code.ros.org/trac/ros/attachment/ticket/3626/ros_comm-1.6.5-rosconsole_g%2B%2B-4.2.patch

From this ticket: https://code.ros.org/trac/ros/ticket/3626

=== Mercurial fails with an import error ===
If you see this error when trying to run `hg`:
{{{
bash-3.2$ hg
Traceback (most recent call last):
 File "/usr/local/bin/hg", line 38, in <module>
   mercurial.dispatch.run()
 File "/Library/Python/2.7/site-packages/mercurial/dispatch.py", line 27, in run
   sys.exit(dispatch(request(sys.argv[1:])))
 File "/Library/Python/2.7/site-packages/mercurial/dispatch.py", line 40, in dispatch
   req.ui = uimod.ui()
 File "/Library/Python/2.7/site-packages/mercurial/ui.py", line 43, in __init__
   for f in scmutil.rcpath():
 File "/Library/Python/2.7/site-packages/mercurial/scmutil.py", line 399, in rcpath
   _rcpath = osrcpath()
 File "/Library/Python/2.7/site-packages/mercurial/scmutil.py", line 371, in osrcpath
   path = systemrcpath()
 File "/Library/Python/2.7/site-packages/mercurial/scmutil.py", line 420, in systemrcpath
   path.extend(rcfiles(os.path.join(p, 'etc/mercurial')))
 File "/Library/Python/2.7/site-packages/mercurial/scmutil.py", line 409, in rcfiles
   for f, kind in osutil.listdir(rcdir)
 File "/Library/Python/2.7/site-packages/mercurial/demandimport.py", line 86, in __getattribute__
   self._load()
 File "/Library/Python/2.7/site-packages/mercurial/demandimport.py", line 58, in _load
   mod = _origimport(head, globals, locals)
ImportError: dlopen(/Library/Python/2.7/site-packages/mercurial/osutil.so, 2): no suitable image found.  Did find:
       /Library/Python/2.7/site-packages/mercurial/osutil.so: mach-o, but wrong architecture
}}}
Then your Python interpreter is running in 32-bit mode.  To put it in 64-bit mode:
{{{
defaults write com.apple.versioner.python Prefer-32-Bit -bool no
}}}

=== Rosdep failes due to md5 sum mismatch ===

This likely means that something has changed in one of the rdmanifests that are hosted on kforge.ros.org and you need to update your global rosdep.yaml file by rerunning the following command to get the latest file.

~-{{{
wget http://kforge.ros.org/rososx/homebrew/raw-file/tip/electric/rosdep.yaml -O ~/.ros/rosdep.yaml
}}}-~

=== wxPython fails to install due to ausparc.com dependency ===

If `wxPython` fails to install with a complaint about not being able to download from mirror.ausparc.com, this means that the `~/.ros/rosdep.yaml` file has a typo in it. You can fix it by editing the file and substituting `wxpython` for `wxPython` as shown:

Turn this:

~-{{{
# Overriding existing wxPython source install
wxPython:
  osxbrew:
}}}-~

into this:

~-{{{
# Overriding existing wxPython source install
wxpython:
  osxbrew:
}}}-~

This bug can surface when following along the tutorials, in the step where you are asked to install the `rxtools` package.

<<Include(electric/Installation/PostInstall)>>