feat(slam): add cartographer_ros

cartographer/scripts/build_test_asan.sh

@@ -0,0 +1,38 @@
+#!/bin/sh
+
+# Copyright 2017 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+# Installing the following packages may be required:
+# sudo apt-get install clang-3.8 llvm-3.8
+
+cd cartographer
+mkdir -p build-asan
+cd build-asan
+cmake .. -G Ninja \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DFORCE_DEBUG_BUILD=True \
+  -DCMAKE_CXXFLAGS="-fno-omit-frame-pointer -fsanitize=address \
+    -fsanitize-address-use-after-scope -O1" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address" \
+  -DCMAKE_C_COMPILER=clang-3.8 \
+  -DCMAKE_CXX_COMPILER=clang++-3.8
+ninja
+PATH="/usr/lib/llvm-3.8/bin/:$PATH" \
+  ASAN_OPTIONS="detect_leaks=1 detect_stack_use_after_return=true" \
+  ctest --output-on-failure -j20 --timeout 60 \
+    --test-arguments="--gtest_color=yes"

cartographer/scripts/ctest_to_junit.py

@@ -0,0 +1,33 @@
+# Copyright 2018 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from lxml import etree
+import StringIO
+import sys
+
+TAGfile = open(sys.argv[1]+"/Testing/TAG", 'r')
+dirname = TAGfile.readline().strip()
+
+xmlfile = open(sys.argv[1]+"/Testing/"+dirname+"/Test.xml", 'r')
+xslfile = open(sys.path[0] + "/ctest_to_junit.xsl", 'r')
+
+xmlcontent = xmlfile.read()
+xslcontent = xslfile.read()
+
+xmldoc = etree.parse(StringIO.StringIO(xmlcontent))
+xslt_root = etree.XML(xslcontent)
+transform = etree.XSLT(xslt_root)
+
+result_tree = transform(xmldoc)
+result_tree.write(sys.argv[1]+"/Testing/"+dirname+"/jUnit.xml")

cartographer/scripts/ctest_to_junit.xsl

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Copyright 2018 The Cartographer Authors
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+	  http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+	<xsl:output method="xml" indent="yes" />
+	<xsl:template match="/">
+		<testsuites>
+			<xsl:variable name="buildName" select="//Site/@BuildName"/>
+			<xsl:variable name="numberOfTests" select="count(//Site/Testing/Test)"/>
+			<xsl:variable name="numberOfFailures" select="count(//Site/Testing/Test[@Status!='passed'])" />
+			<testsuite name="CTest"
+				tests="{$numberOfTests}" time="0"
+				failures="{$numberOfFailures}"  errors="0"
+				skipped="0">
+			<xsl:for-each select="//Site/Testing/Test">
+					<xsl:variable name="testName" select="translate(Name, '-', '_')"/>
+					<xsl:variable name="duration" select="Results/NamedMeasurement[@name='Execution Time']/Value"/>
+					<xsl:variable name="status" select="@Status"/>
+					<xsl:variable name="output" select="Results/Measurement/Value"/>
+					<xsl:variable name="className" select="translate(Path, '/.', '.')"/>
+					<testcase classname="projectroot{$className}"
+						name="{$testName}"
+						time="{$duration}">
+						<xsl:if test="@Status!='passed'">
+							<failure>
+								<xsl:value-of select="$output" />
+							</failure>
+						</xsl:if>
+						<system-out>
+							<xsl:value-of select="$output" />
+						</system-out>
+					</testcase>
+				</xsl:for-each>
+			</testsuite>
+		</testsuites>
+	</xsl:template>
+</xsl:stylesheet>

cartographer/scripts/install_abseil.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+
+# Copyright 2019 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+git clone https://github.com/abseil/abseil-cpp.git
+cd abseil-cpp
+git checkout d902eb869bcfacc1bad14933ed9af4bed006d481
+mkdir build
+cd build
+cmake -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
+  -DCMAKE_INSTALL_PREFIX=/usr/local/stow/absl \
+  ..
+ninja
+sudo ninja install
+cd /usr/local/stow
+sudo stow absl

cartographer/scripts/install_async_grpc.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+
+# Copyright 2018 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+git clone https://github.com/cartographer-project/async_grpc
+cd async_grpc
+git checkout 771af45374af7f7bfc3b622ed7efbe29a4aba403
+mkdir build
+cd build
+cmake -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  ..
+ninja
+sudo ninja install

cartographer/scripts/install_cartographer_bazel.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+
+# Copyright 2016 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+# Build and install Cartographer.
+cd cartographer
+bazel build //...
+bazel test --jobs 1 //...

cartographer/scripts/install_cartographer_cmake.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+
+# Copyright 2016 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+# Build and install Cartographer.
+cd cartographer
+mkdir build
+cd build
+cmake .. -G Ninja
+ninja
+CTEST_OUTPUT_ON_FAILURE=1 ninja test
+sudo ninja install

cartographer/scripts/install_cartographer_cmake_with_grpc.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+
+# Copyright 2017 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+# Build and install Cartographer.
+cd cartographer
+mkdir build
+cd build
+cmake .. -DBUILD_GRPC=ON -DBUILD_PROMETHEUS=ON -G Ninja
+ninja
+CTEST_OUTPUT_ON_FAILURE=1 ninja test
+sudo ninja install

cartographer/scripts/install_ceres.sh

@@ -0,0 +1,31 @@
+#!/bin/sh
+
+# Copyright 2016 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+VERSION="1.13.0"
+
+# Build and install Ceres.
+git clone https://ceres-solver.googlesource.com/ceres-solver
+cd ceres-solver
+git checkout tags/${VERSION}
+mkdir build
+cd build
+cmake .. -G Ninja -DCXX11=ON
+ninja
+CTEST_OUTPUT_ON_FAILURE=1 ninja test
+sudo ninja install

cartographer/scripts/install_debs_bazel.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+
+# Copyright 2016 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+# Install the required libraries that are available as debs.
+sudo apt-get update
+sudo apt-get install -y \
+    wget \
+    pkg-config \
+    zip \
+    g++ \
+    zlib1g-dev \
+    unzip \
+    python
+wget https://github.com/bazelbuild/bazel/releases/download/0.9.0/bazel-0.9.0-installer-linux-x86_64.sh
+chmod +x bazel-0.9.0-installer-linux-x86_64.sh
+./bazel-0.9.0-installer-linux-x86_64.sh
+export PATH="$PATH:$HOME/bin"

cartographer/scripts/install_debs_cmake.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# Copyright 2016 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+# Install the required libraries that are available as debs.
+sudo apt-get update
+sudo apt-get install -y \
+    clang \
+    cmake \
+    g++ \
+    git \
+    google-mock \
+    libboost-all-dev \
+    libcairo2-dev \
+    libcurl4-openssl-dev \
+    libeigen3-dev \
+    libgflags-dev \
+    libgoogle-glog-dev \
+    liblua5.2-dev \
+    libsuitesparse-dev \
+    lsb-release \
+    ninja-build \
+    stow
+
+# Install Ceres Solver and Protocol Buffers support if available.
+# No need to build it ourselves.
+if [[ "$(lsb_release -sc)" = "focal" || "$(lsb_release -sc)" = "buster" ]]
+then
+  sudo apt-get install -y python3-sphinx libgmock-dev libceres-dev protobuf-compiler
+else
+  sudo apt-get install -y python-sphinx
+  if [[ "$(lsb_release -sc)" = "bionic" ]]
+  then
+    sudo apt-get install -y libceres-dev
+  fi
+fi
+
+

cartographer/scripts/install_grpc.sh

@@ -0,0 +1,28 @@
+#!/bin/sh
+
+# Copyright 2017 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+VERSION="v1.10.0"
+# Digest: 474c5950686e3962bd339c93d27e369bf64f568f
+
+# Build and install gRPC.
+git clone --branch ${VERSION} --depth 1 https://github.com/grpc/grpc
+cd grpc
+git submodule update --init
+make
+sudo make install

cartographer/scripts/install_prometheus_cpp.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+
+# Copyright 2018 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+COMMIT="4e0814ee3f93b796356a51a4795a332568940a72"
+
+git clone https://github.com/jupp0r/prometheus-cpp.git
+cd prometheus-cpp
+git checkout ${COMMIT}
+git submodule update --init
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+make
+sudo make install

cartographer/scripts/install_proto3.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+
+# Copyright 2016 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o verbose
+
+VERSION="v3.4.1"
+
+# Build and install proto3.
+git clone https://github.com/google/protobuf.git
+cd protobuf
+git checkout tags/${VERSION}
+mkdir build
+cd build
+cmake -G Ninja \
+  -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
+  -DCMAKE_BUILD_TYPE=Release \
+  -Dprotobuf_BUILD_TESTS=OFF \
+  ../cmake
+ninja
+sudo ninja install

cartographer/scripts/load_docker_cache.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# Copyright 2016 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Cache intermediate Docker layers. For a description of how this works, see:
+# https://giorgos.sealabs.net/docker-cache-on-travis-and-docker-112.html
+
+set -o errexit
+set -o verbose
+set -o pipefail
+
+if [ -f ${DOCKER_CACHE_FILE} ]; then
+  gunzip -c ${DOCKER_CACHE_FILE} | docker load;
+fi

cartographer/scripts/remove_mingw_cygwin_from_path.bat

@@ -0,0 +1,20 @@
+rem  Copyright 2018 The Cartographer Authors
+rem  
+rem  Licensed under the Apache License, Version 2.0 (the "License");
+rem  you may not use this file except in compliance with the License.
+rem  You may obtain a copy of the License at
+rem  
+rem       http://www.apache.org/licenses/LICENSE-2.0
+rem  
+rem  Unless required by applicable law or agreed to in writing, software
+rem  distributed under the License is distributed on an "AS IS" BASIS,
+rem  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+rem  See the License for the specific language governing permissions and
+rem  limitations under the License.
+
+rem  Remove git bash's MinGW/Cygwin stuff from PATH, as it interferes with CMake's
+rem  detection of Boost when using ninja.
+set PATH=%PATH:C:\tools\mingw64\bin;=%
+set PATH=%PATH:C:\Program Files\Git\bin;=%
+set PATH=%PATH:C:\Program Files\Git\usr\bin;=%
+set PATH=%PATH:C:\Program Files\Git\mingw64\bin;=%

cartographer/scripts/save_docker_cache.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# Copyright 2016 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Cache intermediate Docker layers. For a description of how this works, see:
+# https://giorgos.sealabs.net/docker-cache-on-travis-and-docker-112.html
+
+set -o errexit
+set -o verbose
+set -o pipefail
+
+if [[ ${TRAVIS_BRANCH} == "master" ]] &&
+    [[ ${TRAVIS_PULL_REQUEST} == "false" ]]; then
+  mkdir -p $(dirname ${DOCKER_CACHE_FILE})
+  IMAGE_NAMES=$(docker history -q cartographer:${LSB_RELEASE} | grep -v '<missing>')
+  docker save ${IMAGE_NAMES} | gzip > ${DOCKER_CACHE_FILE}.new
+  mv ${DOCKER_CACHE_FILE}.new ${DOCKER_CACHE_FILE}
+fi

cartographer/scripts/update_configuration_doc.py

@@ -0,0 +1,216 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+# Copyright 2016 The Cartographer Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""A dumb configuration.rst generator that relies on source comments."""
+
+import io
+import os
+
+TARGET = 'docs/source/configuration.rst'
+ROOT = 'cartographer'
+PREFIX = """.. Copyright 2016 The Cartographer Authors
+
+.. Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+..      http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+=============
+Configuration
+=============
+
+.. DO NOT EDIT! This documentation is AUTOGENERATED, please edit .proto files as
+.. needed and run scripts/update_configuration_doc.py.
+
+"""
+SUFFIX = """
+"""
+NODOC = 'Not yet documented.'
+
+
+class Message(object):
+  def __init__(self, name, package, preceding_comments):
+    self.name = name
+    self.package = package
+    self.preceding_comments = preceding_comments
+    self.trailing_comments = None
+    self.options = []
+
+  def AddTrailingComments(self, comments):
+    self.trailing_comments = comments
+
+  def AddOption(self, option_type, name, comments):
+    self.options.append((option_type, name, comments))
+
+
+def ParseProtoFile(proto_file):
+  """Computes the list of Message objects of the option messages in a file."""
+  line_iter = iter(proto_file)
+
+  # We ignore the license header and search for the 'package' line.
+  for line in line_iter:
+    line = line.strip()
+    if line.startswith('package'):
+      assert line[-1] == ';'
+      package = line[7:-1].strip()
+      break
+    else:
+      assert '}' not in line
+
+  message_list = []
+  while True:
+    # Search for the next options message and capture preceding comments.
+    message_comments = []
+    for line in line_iter:
+      line = line.strip()
+      if '}' in line:
+        # The preceding comments were for a different message it seems.
+        message_comments = []
+      elif line.startswith('//'):
+        # We keep comments preceding an options message.
+        comment = line[2:].strip()
+        if not comment.startswith('NEXT ID:'):
+          message_comments.append(comment)
+      elif line.startswith('message') and line.endswith('Options {'):
+        message_name = package + '.' + line[7:-1].strip()
+        break
+    else:
+      # We reached the end of file.
+      break
+    print(" Found '%s'." % message_name)
+    message = Message(message_name, package, message_comments)
+    message_list.append(message)
+
+    # We capture the contents of this message.
+    option_comments = []
+    multiline = ''
+    for line in line_iter:
+      line = line.strip()
+      if '}' in line:
+        # We reached the end of this message.
+        message.AddTrailingComments(option_comments)
+        break
+      elif line.startswith('//'):
+        comment = line[2:].strip()
+        if not comment.startswith('NEXT ID:'):
+          option_comments.append(comment)
+      else:
+        assert not line.startswith('required')
+        multiline += ' ' + line
+        if not multiline.endswith(';'):
+          continue
+        assert len(multiline) < 200
+        option = multiline[:-1].strip().rstrip('0123456789').strip()
+        assert option.endswith('=')
+        if option.startswith('repeated'):
+          option = option[8:]
+        option_type, option_name = option[:-1].strip().split();
+        print("  Option '%s'." % option_name)
+        multiline = ''
+        message.AddOption(option_type, option_name, option_comments)
+        option_comments = []
+
+  return message_list
+
+
+def ParseProtoFilesRecursively(root):
+  """Recursively parses all proto files into a list of Message objects."""
+  message_list = []
+  for dirpath, dirnames, filenames in os.walk(root):
+    for name in filenames:
+      if name.endswith('.proto'):
+        path = os.path.join(dirpath, name)
+        print("Found '%s'..." % path)
+        assert not os.path.islink(path)
+        message_list.extend(ParseProtoFile(io.open(path, encoding='UTF-8')))
+  return message_list
+
+
+class ResolutionError(Exception):
+  """Raised when resolving a message name fails."""
+
+
+class Resolver(object):
+  def __init__(self, name_set):
+    self.name_set = set(iter(name_set))
+
+  def Resolve(self, message_name, package_name):
+    if message_name in ('bool', 'double', 'float', 'int32'):
+      return message_name
+    if message_name.startswith('.'):
+      return message_name[1:]
+    package = package_name.split('.')
+    for levels in range(len(package), -1, -1):
+      candidate = '.'.join(package[0:levels]) + '.' + message_name
+      if candidate in self.name_set:
+        return candidate
+    raise ResolutionError(
+        'Resolving %s in %s failed.' % (message_name, package_name))
+
+
+def GenerateDocumentation(output_file, root):
+  """Recursively generates documentation, sorts and writes it."""
+  message_list = ParseProtoFilesRecursively(root)
+  resolver = Resolver(message.name for message in message_list)
+
+  output_dict = {}
+  for message in message_list:
+    content = [message.name, '=' * len(message.name), '']
+    assert message.name not in output_dict
+    output_dict[message.name] = content
+    if message.preceding_comments:
+      content.extend(message.preceding_comments)
+      content.append('')
+    for option_type, option_name, option_comments in message.options:
+      # TODO(whess): For now we exclude InitialTrajectoryPose from the
+      # documentation. It is documented itself (since it has no Options suffix)
+      # and is not parsed from the Lua files.
+      if option_type in ('InitialTrajectoryPose',):
+        continue
+      content.append(
+          resolver.Resolve(option_type, message.package) + ' ' + option_name)
+      if not option_comments:
+        option_comments.append(NODOC)
+      for comment in option_comments:
+        content.append('  ' + comment)
+      content.append('')
+    if message.trailing_comments:
+      content.extend(message.trailing_comments)
+      content.append('')
+
+  output = ['\n'.join(doc) for key, doc in sorted(list(output_dict.items()))]
+  print('\n\n'.join(output), file=output_file)
+
+
+def main():
+  assert not os.path.islink(TARGET) and os.path.isfile(TARGET)
+  assert not os.path.islink(ROOT) and os.path.isdir(ROOT)
+  output_file = io.open(TARGET, mode='w', encoding='UTF-8', newline='\n')
+  output_file.write(PREFIX)
+  GenerateDocumentation(output_file, ROOT)
+  output_file.write(SUFFIX)
+  output_file.close()
+
+
+if __name__ == "__main__":
+  main()