build-tools-from-source.txt

.. _building-tools-from-source:

===============================
Build MongoDB Tools From Source
===============================

.. versionchanged:: 3.0.0

The MongoDB tools provide import, export, and diagnostic capabilities.

As of MongoDB 3.0, MongoDB tools, except for ``mongosniff`` and
``mongoperf``, are written in Go. In order to build and contribute to
them, you will need to ensure you have installed the requisite
dependencies, clone the `mongo-tools
<https://github.com/mongodb/mongo-tools>`_ git repository, and build
the tools.

To build ``mongosniff`` and ``mongoperf``, see
:doc:`/contributors/tutorial/build-mongodb-from-source`.

.. _building-tools-dependencies:

Dependencies
------------

To build the tools, you must have Go version 1.3 or newer. You can download
Go from https://golang.org/dl/.

You will also need ``git``.

Windows users who wish to install the tools with support for SSL or SASL
must also have ``gcc``, which comes bundled with ``mingw``. To use
``gcc``, install `mingw <http://www.mingw.org/>`_ for 32-bit systems, or
`Mingw-64 <http://mingw-w64.sourceforge.net/>`_ for 64-bit systems, then
add the path to ``gcc`` to your ``PATH`` environment variable.

Setup
-----

#. Clone the `mongo-tools repository
   <https://github.com/mongodb/mongo-tools>`_. If you wish to push your
   changes to the core project, you may wish to :ref:`fork the
   repository <github-101-setting-up-a-fork>` and clone your fork
   instead.

#. Set your ``GOPATH`` to include the vendored dependencies by running
   the ``set_gopath.sh`` or ``set_gopath.bat`` helper script from the
   root of the ``mongo-tools`` repository:
   
   .. code-block:: sh
   
      ./set_gopath.sh
   
   .. note::
      
      ``set_gopath.bat`` is designed for use with the Windows Command
      Prompt.

Build the Tools
---------------

Build the Tools on Linux / Unix
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Build the tools with ``go build``:

#. Create the ``bin`` directory where you will install the tools:

   .. code-block:: sh
   
      mkdir bin

#. Build the desired tool with ``go build``, specifying the
   destination with the ``-o`` flag and then the package to build.
   In this case, the destination is ``bin/mongoimport`` and
   the package is ``mongoimport/main/mongoimport.go``:

   .. code-block:: sh
   
      go build -o bin/mongoimport mongoimport/main/mongoimport.go

   If you run ``bin/mongoimport --version``, it will return the
   ``mongoimport`` version (e.g. 3.0.0) and a ``not-built-with-ldflags``
   message for the git version. To build the desired tool with the commit
   gitspec, run instead:

   .. code-block:: sh

      go build -ldflags "-X github.com/mongodb/mongo-tools/common/options.Gitspec `git rev-parse HEAD`" -o bin/mongoimport mongoimport/main/mongoimport.go
   
You can also use the ``-tags`` flag to tell ``go build`` to build the
tools with support for SSL and/or SASL:

.. code-block:: sh

   go build -o bin/mongoimport -tags ssl mongoimport/main/mongoimport.go
   go build -o bin/mongoimport -tags "ssl sasl" mongoimport/main/mongoimport.go

Build the Tools on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~

You build the tools on Windows in much the same way as Linux/Unix users,
using ``go build``:

#. Create the ``bin`` directory where you will install the tools.

#. From the root of the ``mongo-tools`` directory, build the desired
   tool with ``go build``, specifying the destination with the ``-o``
   flag and then the package to build. In this case, the destination is
   ``\bin\mongoimport.exe`` and the package is
   ``\mongoimport\main\mongoimport.go``:

   .. code-block:: none
   
      go build -o .\bin\mongoimport.exe .\mongoimport\main\mongoimport.go

   If you run ``.\bin\mongoimport.exe --version``, it will return the
   ``mongoimport`` version (e.g. 3.0.0) and a ``not-built-with-ldflags``
   message for the git version.
      
   To build the desired tool with the commit gitspec, run instead:

   .. code-block:: sh

      for /f "delims=" %g in ('git rev-parse HEAD') do go build -ldflags "-X github.com/mongodb/mongo-tools/common/options.Gitspec %g" -o .\bin\mongoimport.exe .\mongoimport\main\mongoimport.go

If you :ref:`have installed gcc <building-tools-dependencies>`, you can
also use the ``-tags`` flag to tell ``go build`` to build the tools with
support for SSL and/or SASL:

.. code-block:: none

   go build -o .\bin\mongoimport.exe -tags ssl .\mongoimport\main\mongoimport.go
   go build -o .\bin\mongoimport.exe -tags "ssl sasl" .\mongoimport\main\mongoimport.go

Whenever you make changes to the tools code, you must
run ``set_gopath.bat`` again **before** rebuilding the tools or the
changes will not be captured by the build.