From e5c5224ede4dfc159340293fe99469f9e17d21e2 Mon Sep 17 00:00:00 2001 From: Jonathan Bohren Date: Tue, 15 Dec 2015 20:15:53 -0500 Subject: [PATCH 01/10] doc: Adding documentation for forthcoming changes in 0.4.0, updating local sphinx style, and reorganizing main index --- docs/advanced/executor_events.dia | 1185 ++++ docs/advanced/executor_events.svg | 475 ++ docs/advanced/executor_job_lifecycle.svg | 319 + docs/advanced/executor_job_resources.svg | 472 ++ docs/advanced/job_executor.rst | 196 + docs/build_types.rst | 92 + docs/catkin_build.dia | 1063 ++++ docs/catkin_tools_execution.dia | 5147 +++++++++++++++++ docs/conf.py | 7 +- docs/development/adding_build_types.rst | 75 + .../extending_the_catkin_command.rst | 3 +- docs/executor_job_lifecycle.dia | 612 ++ docs/executor_job_lifecycle.svg | 766 +++ docs/index.rst | 60 +- docs/installing.rst | 2 +- docs/verbs/catkin_build.rst | 622 +- .../{catkin_find.rst => catkin_locate.rst} | 4 +- 17 files changed, 10749 insertions(+), 351 deletions(-) create mode 100644 docs/advanced/executor_events.dia create mode 100644 docs/advanced/executor_events.svg create mode 100644 docs/advanced/executor_job_lifecycle.svg create mode 100644 docs/advanced/executor_job_resources.svg create mode 100644 docs/advanced/job_executor.rst create mode 100644 docs/build_types.rst create mode 100644 docs/catkin_build.dia create mode 100644 docs/catkin_tools_execution.dia create mode 100644 docs/development/adding_build_types.rst create mode 100644 docs/executor_job_lifecycle.dia create mode 100644 docs/executor_job_lifecycle.svg rename docs/verbs/{catkin_find.rst => catkin_locate.rst} (95%) diff --git a/docs/advanced/executor_events.dia b/docs/advanced/executor_events.dia new file mode 100644 index 00000000..0a500f04 --- /dev/null +++ b/docs/advanced/executor_events.dia @@ -0,0 +1,1185 @@ + + + + + + + + + + + + + #Letter# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Executor# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Event Queue# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Output Controller# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #stdout# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #stderr# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Command Stages# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #stdout# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #stderr# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #IO Protocol# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Function Stages# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #IO Logger# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/advanced/executor_events.svg b/docs/advanced/executor_events.svg new file mode 100644 index 00000000..0362d50d --- /dev/null +++ b/docs/advanced/executor_events.svg @@ -0,0 +1,475 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/advanced/executor_job_lifecycle.svg b/docs/advanced/executor_job_lifecycle.svg new file mode 100644 index 00000000..bd797875 --- /dev/null +++ b/docs/advanced/executor_job_lifecycle.svg @@ -0,0 +1,319 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/advanced/executor_job_resources.svg b/docs/advanced/executor_job_resources.svg new file mode 100644 index 00000000..8a3c7ccf --- /dev/null +++ b/docs/advanced/executor_job_resources.svg @@ -0,0 +1,472 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/advanced/job_executor.rst b/docs/advanced/job_executor.rst new file mode 100644 index 00000000..fe384177 --- /dev/null +++ b/docs/advanced/job_executor.rst @@ -0,0 +1,196 @@ +The Catkin Execution Engine +=========================== + +One of the core modules in ``catkin_tools`` is the **job executor**. The +executor performs jobs required to complete a task in a way that maximizes (or +achives a specific) resource utilization subject to job dependency constraints. +The executor is closely integrated with logging and job output capture. This +page details the design and implementation of the executor. + +Execution Model +^^^^^^^^^^^^^^^ + +The execution model is fairly simple. The executor executes a single **task** +for a given command (i.e. ``build``, ``clean``, etc.). A **task** is a set of +**jobs** which are related by an acyclic dependency graph. Each **job** is +given a unique identifier and is composed of a set of dependencies and a +sequence of executable **stages**, which are arbitrary functions or subprocess +calls which utilize one or more **workers** to be executed. The allocation of +workers is managed by the **job server**. Throughout execution, synchronization +with the user-facing interface and output formatting are mediated by a simple +**event queue**. + +The executor is single-threaded and uses an asynchronous loop to execute jobs +as futures. If a job contains blocking stages it can utilize a normal thread +pool for execution, but is still only guaranteed one worker by the main loop of +the executor. See the following section for more information on workers and the +job server. + +The input to the executor is a list of topologically-sorted jobs with no +circular dependencies and some parameters which control the jobserver behavior. +These behavior parameters are explained in detail in the following section. + +Each job is in one of the following lifecycle states at any time: + + - ``PENDING`` Not ready to be executed (dependencies not yet completed) + - ``QUEUED`` Ready to be executed once workers are available + - ``ACTIVE`` Being executed by one or more workers + - ``FINISHED`` Has been executed and either succeded or failed (terminal) + - ``ABANDONED`` Was not built because a prerequisite was not met (terminal) + +.. figure:: executor_job_lifecycle.svg + :scale: 50 % + :alt: Executor Job Lifecycle + + **Executor Job lifecycle** + +All jobs begin in the ``PENDING`` state, and any jobs with unsatisfiable +dependencies are immediately set to ``ABANDONED``, and any jobs without +dependencies are immediately set to ``QUEUED``. After the state initialization, +the executor processes jobs in a main loop until they are in one of the two +terminal states (``FINISHED`` or ``ABANDONED``). + +Each main loop iteration does the following: + + - While job server tokens are available, create futures for ``QUEUED`` jobs + and make them ``ACTIVE`` + - Report status of all jobs to the event queue + - Retrieve ``ACTIVE`` job futures which have completed and set them + ``FINISHED`` + - Check for any ``PENDING`` jobs which need to be ``ABANDONED`` due to failed + jobs + - Change all ``PENDING`` jobs whose dependencies are satisifed to ``QUEUED`` + +Once each job is in one of terminal states, the executor pushes a final status +event and returns. + + +Job Server Resource Model +^^^^^^^^^^^^^^^^^^^^^^^^^ + +As mentioned in the previous section, each task includes a set of jobs which +are activated by the **job server**. In order to start a queued job, at least +one worker needs to be available. Once a job is started, it is assigned a +single worker from the job server. These are considered **top-level jobs** +since they are managed directly by the catkin executor. The number of top-level +jobs can be configured for a given task. + +Additionally to top-level paralellism, some job stages are capable of running +in parallel, themselves. In such cases, the job server can interface directly +with the underlying stage's low-level job allocation. This enables multi-level +parallelism without allocating more than a fixed number of jobs. + + +.. figure:: executor_job_resources.svg + :scale: 50 % + :alt: Executor job resources + + **Executor Job Flow and Resource Utilization** -- In this snapshot of the job pipeline, the executor is executing four of six possible top-level jobs, each with three stages, and using sevel of eight total workers. Two jobs are executing subprocesses, which have side-channel communication with the job server. + +One such parallel-capable stage is the GNU Make build stage. In this case, the +job server implements a GNU Make job server interface, which involves reading +and writing tokens from file handles passed as build flags to the Make command. + +For top-level jobs, additional resources are monitored in addition to the +number of workers. Both system load and memory utilization checks can be +enabled to prevent overloading a system. + +Executor Job Failure Behavior +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The executor's behavior when a job fails can be modified with the following two +parameters: + + - ``continue_on_failure`` Continue executing jobs even if one job fails. If + this is set to ``false`` (the default), it will cause the executor to + abandon all pending and queued jobs and stop after the first failure. Note + that active jobs will still be allowed to complete before the executor + returns. + - ``continue_without_deps`` Continue executing jobs even if one + or more of their dependencies have failed. If this is set to ``false`` (the + default), it will cause the executor to abandon only the jobs which depend + on the failed job. If it is set to ``true``, then it will build dependent + jobs regardless. + + +Jobs and Job Stages +^^^^^^^^^^^^^^^^^^^ + +As mentioned above, a **job** is a set of dependencies and a sequence of **job +stages**. Jobs and stages are constructed before a given task starts executing, +and hold only specificaitons of what needs to be done to complete them. All +stages are given a label for user introspection, a logger interface, and can +either require or not require allocation of a worker from the job server. + +Stage execution is performed asynchronously by Python's ``asyncio`` module. +This means that exceptions thrown in job stages are handled directly by the +executor. It also means job stages can be interrupted easily through Python's +normal signal handling mechanism. + +Stages can either be **command stages** (subprocess commands) or **function +stages** (python functions). In either case, loggers used by stages support +segmentation of ``stdout`` and ``stderr`` from job stages for both real-time +introspection and logging. + + +Command Stages +~~~~~~~~~~~~~~~ + +In addition to the basic arguments mentioned above, command stages are +paramterized by the standard subprocess command arguments including the +following: + + - The command, itself, and its arguments, + - The working directory for the command, + - Any additional environment variables, + - Whether to use a shell interpreter + - Whether to emulate a TTY + - Whether to partition ``stdout`` and ``stderr`` + +When executed, command stages use ``asncio``'s asynchronous process executor +with a custom I/O protocol. + +Function Stages +~~~~~~~~~~~~~~~ + +In addition to the basic arguments mentioned above, function stages are +parameterized by a function handle and a set of function-specific Python +arguments and keyword arguments. When executed, they use the thread pool +mentioned above. + +Since the function stages aren't subprocesses, I/O isn't piped or redirected. +Instead, a custom I/O logger is passed to the function for output. Functions +used as function stages should use this logger to write to ``stdout`` and +``stderr`` instead of using normal system calls. + +Introspection via Executor Events +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Introspection into the different asynchronously-executed components of a task +is performed by a simple event queue. Events are created by the executor, +loggers, and stages, and they are consumed by an output controller. Events are +defined by an event identifier and a data payload, which is an arbitrary +dictionary. + +There are numerous events which correspond to changes in job states, but events are also used for transporting captured I/O from job stages. + +.. figure:: executor_events.svg + :scale: 50 % + :alt: Executor Event Pipeline + + **Executor Event Pipeline** -- Above, the executor writes events to the event queue, and the I/O loggers used by function and command stages write output events as well. All of these events are handled by the output controller, which writes to the real ``stdout`` and ``stderr``. + +The modeled events include the following: + + - ``JOB_STATUS`` A report of running job states, + - ``QUEUED_JOB`` A job has been queued to be executed, + - ``STARTED_JOB`` A job has started to be executed, + - ``FINISHED_JOB`` A job has finished executing (succeeded or failed), + - ``ABANDONED_JOB`` A job has been abandoned for some reason, + - ``STARTED_STAGE`` A job stage has started to be executed, + - ``FINISHED_STAGE`` A job stage has finished executing (succeeded or failed), + - ``STAGE_PROGRESS`` A job stage has executed partially, + - ``STDOUT`` A status message from a job, + - ``STDERR`` A warning or error message from a job, + - ``SUBPROCESS`` A subprocess has been created, + - ``MESSAGE`` Arbitrary string message diff --git a/docs/build_types.rst b/docs/build_types.rst new file mode 100644 index 00000000..51d55f77 --- /dev/null +++ b/docs/build_types.rst @@ -0,0 +1,92 @@ +Supported Build Types +===================== + +The current release of ``catkin_tools`` supports building two types of packages: + + - **Catkin** -- CMake packages that use the Catkin CMake macros + - **CMake** -- "Plain" CMake packages + +There is currently limited support for adding other build types. For information +on extending ``catkin_tools`` to be able to build other types of packages, see +:doc:`Adding New Build Types `. Below are +details on the stages involved in building a given package for each of +the currently-supported build types. + +Catkin +^^^^^^ + +Catkin packages are CMake packages which utilize the Catkin CMake macros for +finding packages and defining configuration files. + +Configuration Arguments +----------------------- + + - ``--cmake-args`` + - ``--make-args`` + - ``--catkin-make-args`` + +Build Stages +------------ + +============== ============ ================================================== + First Subsequent Description +============== ============ ================================================== + ``mkdir`` | Create package build space if it doesn't exist. +---------------------------- -------------------------------------------------- + ``envgen`` | Generate environment setup file for building. +---------------------------- -------------------------------------------------- + ``cmake`` ``check`` | Run CMake configure step **once** for the + | first build and the ``cmake_check_build_system`` + | target for subsequent builds unless the + | ``--force-cmake`` argument is given. +-------------- ------------ -------------------------------------------------- + ``preclean`` `optional` | Run the ``clean`` target before building. + | This is only done with the ``--pre-clean`` \ + option. +---------------------------- -------------------------------------------------- + ``make`` | Build the default target with GNU make. +---------------------------- -------------------------------------------------- + ``install`` `optional` | Run the ``install`` target after building. + | This is only done with the ``--install`` option. +============================ ================================================== + +CMake +^^^^^ + +Configuration Arguments +----------------------- + + - ``--cmake-args`` + - ``--make-args`` + +Build Stages +------------ + +============== ============ ================================================== + First Subsequent Description +============== ============ ================================================== + ``mkdir`` | Create package build space if it doesn't exist. +---------------------------- -------------------------------------------------- + ``envgen`` | Generate environment setup file for building. +---------------------------- -------------------------------------------------- + ``cmake`` ``check`` | Run CMake configure step **once** for the + | first build and the ``cmake_check_build_system`` + | target for subsequent builds unless the + | ``--force-cmake`` argument is given. +-------------- ------------ -------------------------------------------------- + ``preclean`` `optional` | Run the ``clean`` target before building. + | This is only done with the ``--pre-clean`` \ + option. +---------------------------- -------------------------------------------------- + ``make`` | Build the default target with GNU make. +---------------------------- -------------------------------------------------- + ``install`` | Run the ``install`` target after building, + | and install products to the **devel space**. + | If the ``--install`` option is given, + | products are installed to the \ + **install space** instead. +---------------------------- -------------------------------------------------- + ``setupgen`` | Generate a ``setup.sh`` file if necessary. +============================ ================================================== + + diff --git a/docs/catkin_build.dia b/docs/catkin_build.dia new file mode 100644 index 00000000..a5ae26f8 --- /dev/null +++ b/docs/catkin_build.dia @@ -0,0 +1,1063 @@ + + + + + + + + + + + + + #Letter# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #catkin build# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #CMake# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #CMake# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #...# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #CMake# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GNU Make# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GNU Make# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GNU Make# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #pkg_a# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #pkg_b# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #pkg_c# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #pkg_d# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #pkg_x# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #pkg_y# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #pkg_z# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/catkin_tools_execution.dia b/docs/catkin_tools_execution.dia new file mode 100644 index 00000000..3b392861 --- /dev/null +++ b/docs/catkin_tools_execution.dia @@ -0,0 +1,5147 @@ + + + + + + + + + + + + + #Letter# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #stage 1# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #stage m# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #job 1# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #.# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #.# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #.# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #task# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #.# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #.# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #.# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #JobServer# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #stage 1# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #stage m# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #job n# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #.# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #.# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #.# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #PENDING# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #QUEUED# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #ACTIVE# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #COMPLETED# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #ABANDONED# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Dependencies +Completed# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Worker +Available# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Success +or Failure# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Dependency Failed or +Peer Failed (CoF disabled)# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #...# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #...# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #...# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #...# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Pending Job Set# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Queued Job Queue# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Active Job Set (4/6 High-Level Jobs)# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Finished Job Set# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Abandoned Job Set# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Job Server (7/8 Low-Level Workers)# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Subprocess to +Job Server +Interfaces# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/conf.py b/docs/conf.py index 7fa36629..20a4795f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -104,9 +104,14 @@ # -- Options for HTML output ---------------------------------------------- +import sphinx_rtd_theme +html_theme = "sphinx_rtd_theme" +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + + # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +#html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/development/adding_build_types.rst b/docs/development/adding_build_types.rst new file mode 100644 index 00000000..5d0b8bcd --- /dev/null +++ b/docs/development/adding_build_types.rst @@ -0,0 +1,75 @@ +Adding New Build Types +====================== + +The current release of ``catkin_tools`` supports building two types of packages: + + - **Catkin** -- CMake packages that use the Catkin CMake macros + - **CMake** -- "Plain" CMake packages + +In order to fully support additional build types, numerous additions need to be +made to the command-line interfaces so that the necessary parameters can be passed +to the ``build`` verb. For partial support, however, all that's needded is to +add a build type identifier and a function for generating build jobs. + +The supported build typs are easily extendable using the ``setuptools`` +``entry_points`` interface without modifying the ``catkin_tools`` project, +itself. Regardless of what package the ``entry_point`` is defined in, it will +be defined in the ``setup.py`` of that package, and will take this form: + +.. code-block:: python + + from setuptools import setup + + setup( + ... + entry_points={ + ... + 'catkin_tools.jobs': [ + 'mybuild = my_package.some.module:description', + ], + }, + ) + +This entry in the ``setup.py`` places a file in the ``PYTHONPATH`` when either +the ``install`` or the ``develop`` verb is given to ``setup.py``. This file +relates the key (in this case ``mybuild``) to a module and attribute (in this +case ``my_package.some.module`` and ``description``). + +Then the ``catkin`` command will use the ``pkg_resources`` modules to retrieve +these mapping at run time. Any entry for the ``catkin_tools.jobs`` group must +point to a ``description`` attribute of a module, where the ``description`` +attribute is a ``dict``. The ``description`` ``dict`` should take this form: + +.. code-block:: python + + description = dict( + build_type='mybuild', + description="Builds a package with the 'mybuild' build type", + create_build_job=create_mybuild_build_job + ) + +This ``dict`` defines all the information that the ``catkin`` command needs to +create jobs for the ``mybuild`` build type. The ``build_type`` key takes a +string which is the build type identifier. The ``description`` key takes a +string which briefly describes the build type. The ``create_build_job`` key +takes a callable (function) factory which is called in order to create a +``Job`` to build a package of type ``mybuild``. + +The signature of the factory callable should be similar to the following: + +.. code-block:: python + + def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs): + # Initialize empty list of build stages + stages = [] + + # Add stages required to build ``mybuild``-type packages, + # based on the configuration context. + # ... + + # Create and return new build Job + return Job( + jid=package.name, + deps=dependencies, + stages=stages) + diff --git a/docs/development/extending_the_catkin_command.rst b/docs/development/extending_the_catkin_command.rst index 921efc4a..ada43d31 100644 --- a/docs/development/extending_the_catkin_command.rst +++ b/docs/development/extending_the_catkin_command.rst @@ -1,8 +1,7 @@ Extending the ``catkin`` command ================================ -The ``catkin`` command is setup to be easily extended using the ``setuptools`` notion of ``entry_points``, see: http://guide.python-distribute.org/creation.html#entry-points -By using the ``entry_points`` extensions to the ``catkin`` command can be made within the ``catkin_tools`` package or an external package. +The ``catkin`` command is designed to be easily extendable using the ``setuptools`` ``entry_points`` interface without modifying the ``catkin_tools`` project, itself. Regardless of what package the ``entry_point`` is defined in, it will be defined in the ``setup.py`` of that package, and will take this form: .. code-block:: python diff --git a/docs/executor_job_lifecycle.dia b/docs/executor_job_lifecycle.dia new file mode 100644 index 00000000..7f523dd2 --- /dev/null +++ b/docs/executor_job_lifecycle.dia @@ -0,0 +1,612 @@ + + + + + + + + + + + + + #Letter# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #PENDING# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #QUEUED# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #ACTIVE# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #COMPLETED# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #ABANDONED# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Dependencies +Completed# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Worker +Available# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Success +or Failure# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #Dependency Failed or +Peer Failed (CoF disabled)# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/executor_job_lifecycle.svg b/docs/executor_job_lifecycle.svg new file mode 100644 index 00000000..a6ee6366 --- /dev/null +++ b/docs/executor_job_lifecycle.svg @@ -0,0 +1,766 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/index.rst b/docs/index.rst index c1407918..7405d218 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,6 +2,9 @@ Catkin Command Line Tools ========================= .. toctree:: + :name: tocmain + :caption: Main Overview + :glob: :hidden: :maxdepth: 2 @@ -10,19 +13,47 @@ Catkin Command Line Tools mechanics config_summary cheat_sheet + build_types Troubleshooting - verbs/catkin_build - verbs/catkin_clean - verbs/catkin_config - verbs/catkin_create - verbs/catkin_init - verbs/catkin_list - verbs/catkin_locate - verbs/catkin_profile - Advanced: Shell support - Advanced: Verb Aliasing - Advanced: Contributing Verbs -.. TODO: Advanced: Workspace Chaining + +.. toctree:: + :name: tocverbs + :caption: Verb Details + :glob: + :hidden: + :maxdepth: 2 + + verbs/* + +.. toctree:: + :name: tocadv + :caption: Advanced Usage + :glob: + :hidden: + :maxdepth: 2 + + Shell Support + Verb Aliasing +.. Workspace Chaining + +.. toctree:: + :name: tocdes + :caption: Design + :glob: + :hidden: + :maxdepth: 2 + + Execution Engine + +.. toctree:: + :name: toccontrib + :caption: Contributing + :glob: + :hidden: + :maxdepth: 2 + + development/adding_build_types + Adding New Verbs This Python package provides command line tools for working with the catkin meta-buildsystem and catkin workspaces. @@ -39,6 +70,10 @@ This Python package provides command line tools for working with the catkin meta The ``catkin`` command ^^^^^^^^^^^^^^^^^^^^^^ +.. .. raw:: html +.. +.. + The ``catkin`` Command-Line Interface (CLI) tool is the single point of entry for most of the functionality provided by this package. All invocations of the ``catkin`` CLI tool take this form: @@ -70,6 +105,7 @@ Each of the following verbs is built-in to the ``catkin`` command and has its ow - :doc:`create -- Create structures like Catkin packages ` - :doc:`init -- Initialize a catkin workspace ` - :doc:`list -- Find and list information about catkin packages in a workspace ` +- :doc:`locate -- Get important workspace directory paths ` - :doc:`profile -- Manage different named configuration profiles ` Shell support in ``catkin`` command diff --git a/docs/installing.rst b/docs/installing.rst index d3ccb803..2114f549 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -50,7 +50,7 @@ Then install with the ``setup.py`` file: .. code-block:: bash $ python setup.py install - + Note: Depending on your environment/machine, you may need to use ``sudo`` with this command. Developing diff --git a/docs/verbs/catkin_build.rst b/docs/verbs/catkin_build.rst index c188b53c..1e276e6f 100644 --- a/docs/verbs/catkin_build.rst +++ b/docs/verbs/catkin_build.rst @@ -1,10 +1,10 @@ ``catkin build`` -- Build Packages ================================== -The ``build`` verb for the ``catkin`` command is used to build one or more packages in a catkin workspace. -Like most ``catkin`` verbs, the ``catkin build`` verb is context-aware. This means that it can be executed from within any directory contained by an *initialized* workspace. +The ``build`` verb is used to build one or more packages in a catkin workspace. +Like most verbs, ``build`` is context-aware. This means that it can be executed from within any directory contained by an *initialized* workspace. -If a workspace is not yet initialized, ``catkin build`` can initialize it, but only if it is called from the workspace root and the default workspace structure is desired. +If a workspace is not yet initialized, ``build`` can initialize it, but only if it is called from the workspace root and the default workspace structure is desired. Workspaces can also be built from arbitrary working directories if the user specifies the path to the workspace with the ``--workspace`` option. @@ -26,26 +26,12 @@ Workspaces can also be built from arbitrary working directories if the user spec Basic Usage ^^^^^^^^^^^ -Consider a Catkin workspace with a **source space** populated with the -following Catkin packages which have yet to be built: - -.. code-block:: bash - - $ pwd - /tmp/path/to/my_catkin_ws - - $ ls ./* - ./src: - catkin console_bridge genlisp genpy - message_runtime ros_comm roscpp_core std_msgs - common_msgs gencpp genmsg message_generation - ros ros_tutorials rospack Previewing The Build -------------------- -Before actually building anything in the workspace, it is useful to preview which -packages ``catkin build`` will build, and in what order. This can be done with the +Before actually building anything in the workspace, it is useful to preview +which packages will be built and in what order. This can be done with the ``--dry-run`` option: .. code-block:: bash @@ -123,118 +109,11 @@ above are: * **metapackage** -- A package which contains no build products, but just groups other packages together for distribution -Building Specific Packages --------------------------- - -In addition to the usage above, the ``--dry-run`` option will show what the -behavior of ``catkin build`` will be with various other options. -For example, the following will happen when you specify a single package to -build: - -.. code-block:: bash - - $ catkin build roscpp_tutorials --dry-run - .... - Found '36' packages in 0.1 seconds. - Packages to be built: - - catkin (catkin) - - genmsg (catkin) - - gencpp (catkin) - - genlisp (catkin) - - genpy (catkin) - - console_bridge (cmake) - - cpp_common (catkin) - - message_generation (catkin) - - message_runtime (catkin) - - rosbuild (catkin) - - roscpp_traits (catkin) - - roslang (catkin) - - rospack (catkin) - - roslib (catkin) - - rostime (catkin) - - roscpp_serialization (catkin) - - rosunit (catkin) - - rosconsole (catkin) - - std_msgs (catkin) - - rosgraph_msgs (catkin) - - xmlrpcpp (catkin) - - roscpp (catkin) - - roscpp_tutorials (catkin) - Total packages: 23 - -As shown above, only 23 packages (``roscpp_tutorials`` and its dependencies), -of the total 36 packages would be built. - -Skipping Packages ------------------ - -Suppose you built every package up to ``roscpp_tutorials``, but that package -had a build error. -After fixing the error, you could run the same build command again, but the -``build`` verb provides an option to save time in this situation. -If re-started from the beginning, none of the products of the dependencies of -``roscpp_tutorials`` would be re-built, but it would still take some time for -the underlying byuildsystem to verify that for each package. - -Those checks could be skipped, however, by jumping directly to a given package. -You could use the ``--start-with`` option to continue the build where you left -off after fixing the problem. (The following example uses the ``--dry-run`` -option again to preview the behavior): - -.. code-block:: bash - - $ catkin build roscpp_tutorials --start-with roscpp_tutorials --dry-run - .... - Found '36' packages in 0.0 seconds. - Packages to be built: - (skip) catkin (catkin) - (skip) genmsg (catkin) - (skip) gencpp (catkin) - (skip) genlisp (catkin) - (skip) genpy (catkin) - (skip) console_bridge (cmake) - (skip) cpp_common (catkin) - (skip) message_generation (catkin) - (skip) message_runtime (catkin) - (skip) rosbuild (catkin) - (skip) roscpp_traits (catkin) - (skip) roslang (catkin) - (skip) rospack (catkin) - (skip) roslib (catkin) - (skip) rostime (catkin) - (skip) roscpp_serialization (catkin) - (skip) rosunit (catkin) - (skip) rosconsole (catkin) - (skip) std_msgs (catkin) - (skip) rosgraph_msgs (catkin) - (skip) xmlrpcpp (catkin) - (skip) roscpp (catkin) - ------ roscpp_tutorials (catkin) - Total packages: 23 - -However, you should be careful when using the ``--start-with`` option, as -``catkin build`` will assume that all dependencies leading up to that package -have already been successfully built. - -If you're only interested in building a *single* package in a workspace, you -can also use the ``--no-deps`` option along with a package name. This will -skip all of the package's dependencies, build the given package, and then exit. - -.. code-block:: bash - - $ catkin build roscpp_tutorials --no-deps roscpp_tutorials --dry-run - .... - Found '36' packages in 0.0 seconds. - Packages to be built: - - roscpp_tutorials (catkin) - Total packages: 1 - -Build Products --------------- +Building a Workspace +-------------------- -At this point the workspace has not been modified, but once we tell the -``build`` verb to actually build the workspace then directories for a **build -space** and a **devel space** will be created: +When no packages are given as arguments, ``catkin build`` builds the entire workspace. +It automatically creates directories for a **build space** and a **devel space**: .. code-block:: bash @@ -273,13 +152,7 @@ space** and a **devel space** will be created: [build] Finished. [build] Runtime: 3 minutes and 54.6 seconds -Since no packages were given as arguments, ``catkin build`` built all of -the packages in the workspace. - -As shown above, after the build finishes, we now have a **build space** with a -folder containing the intermediate build products for each package and a -**devel space** with an FHS layout into which all the final build products have -been written. +After the build finishes, the **build space** contains directories containing the intermediate build products for each package, and the **devel space** contains an FHS layout into which all the final build products are written. .. code-block:: bash @@ -314,82 +187,40 @@ been written. ``catkin_make_isolated`` which would have an isolated FHS directory for each package in the **devel space**. -Context-Aware Building -^^^^^^^^^^^^^^^^^^^^^^ - -In addition to building all packages or specified packages with various dependency requirements, -``catkin build`` can also determine the package containing the current working directory. This -is equivalent to specifying the name of the package on the command line, and is -done by passing the ``--this`` option to ``catkin build`` like the following: - -.. code-block:: bash - - $ cd /tmp/path/to/my_catkin_ws/src/roscpp_tutorials - $ catkin build --this --dry-run - .... - Found '36' packages in 0.0 seconds. - Packages to be built: - - roscpp_tutorials (catkin) - Total packages: 1 - -Controlling the Number of Build Jobs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default ``catkin build`` on a computer with ``N`` cores will build up to -``N`` packages in parallel and will distribute ``N`` ``make`` jobs among them -using an internal jobserver. If your platform doesn't support jobserver -scheduling, ``catkin build`` will pass ``-jN -lN`` to ``make`` for each package. - -You can control the maximum number of packages allowed to build in parallel by -using the ``-p`` or ``--parallel-packages`` option and you can change the -number of ``make`` jobs available with the ``-j`` or ``--jobs`` option. - -By default, these jobs options aren't passed to the underlying ``make`` -command. To disable the jobserver, you can use the ``--no-jobserver`` option, and -you can pass flags directly to ``make`` with the ``--make-args`` option. - -.. note:: - - Jobs flags (``-jN`` and/or ``-lN``) can be passed directly to ``make`` by - giving them to ``catkin build``, but other ``make`` arguments need to be - passed to the ``--make-args`` option. - -Controlling Command-Line Output -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Status Line ----------- -While running ``catkin build`` with default options, you would have seen the -"live" status lines similar to the following: +When running ``catkin build`` with default options, it displays a "live" status line similar to the following: .. code-block:: none - [build - 5.9] [genmsg - 1.3] [message_runtime - 0.7] ... [4/4 Active | 3/36 Completed] - -This status line stays at the bottom of the screen and displays the continuously-updated progress -of the entire build as well as the active build jobs which are still running. It is composed -of the following information: - - * **Total Build Time** -- The first block on the left, indicates the total - elapsed build time in seconds thus far. Above, ``[build - 5.9]`` means that - the build has been running for a total of ``5.9`` seconds. - * **Active Job Status** -- The next blocks show the currently active jobs with as - name of the package being built and the elapsed time for that job, in - seconds. The above block like ``[genmsg - 1.3]`` means that the ``genmsg`` - package is currently being built, and it has been building for ``1.3`` - seconds. - * **Active and Completed Counts** -- The final block, justified to the right, - is the number of packages being actively built out of the total allowed - parallel jobs (specified with the ``-p`` options) as well as the number of - completed packages out of the total. Above, the block ``[4/4 Active | 3/36 - Completed]`` means that there are four out of four jobs active and three of - the total 36 packages to be built have been completed. - -This status line can be disabled by passing the ``--no-status`` option to ``catkin build``. - -Package Build Messages ----------------------- + [build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ... + +The status line stays at the bottom of the screen and displays the continuously-updated progress of the entire build as well as the active build jobs which are still running. It is composed of the following information: + + * ``[build - ]`` -- The first block on the left indicates the total elapsed + build time ```` in seconds thus far. + * ``[/ complete]`` -- The second block from the left indicates the + build progress in terms of the number of completed packages, ```` out of + the total number of packages to be built ````. + * ``[/ jobs]`` -- The third block from the left indicates the number of + active total low-level jobs ```` out of the total number of low-level + workers ````. + * ``[ queued]`` -- The fourth block from the left indicates the number of + jobs ```` whose dependencies have already been satisfied and are ready to + be built. + * ``[ failed]`` -- The fifth block from the left indicates the number of + jobs ```` which have failed. This block only appears once one or more + jobs has failed. + * ``[: (

%) - ]`` -- The remaining blocks show details on + the active jobs. These include the percent complete, ``

``, of the stage, + if available, as well as the time elapsed building the package, ````. + +When necessary, the status line can be disabled by passing the ``--no-status`` option to ``catkin build``. +This is sometimes required when running ``catkin build`` from within a program that doesn't support the ASCII escape sequences required to reset and re-write the status line. + +Console Messages +---------------- Normally, unless an error occurs, the output from each package's build proces is collected but not printed to the console. All that is printed is a pair of @@ -398,91 +229,254 @@ like the following for the ``genmsg`` package: .. code-block:: none - Starting ==> genmsg - Finished <== genmsg [ 2.4 seconds ] + ... + Starting >>> genmsg + ... + Finished <<< genmsg [ 0.1 seconds ] + ... -However, if you would like to see more of the messages from the underlying -buildsystem, you can invoke the ``-v`` or ``--verbose`` option. -This will print the normal message when a package build starts and finished as -well as the output of each build command in a block, once it finishes: +Error messages are printed whenever a build job writes to ``stderr``. +In such cases, the ``build`` verb will automatically print the captured ``stderr`` buffer under a ``Warnings`` header once the job has completed, similarly to below: .. code-block:: none - Starting ==> catkin + ... + ____________________________________________________________________________ + Warnings << rospack:make /path/to/my_catkin_ws/build/_logs/rospack/build.make.000.log + In file included from /usr/include/python2.7/Python.h:8:0, + from /path/to/my_catkin_ws/src/rospack/src/rospack.cpp:71: + /usr/include/python2.7/pyconfig.h:1161:0: warning: "_POSIX_C_SOURCE" redefined [enabled by default] + /usr/include/features.h:164:0: note: this is the location of the previous definition + /usr/include/python2.7/pyconfig.h:1183:0: warning: "_XOPEN_SOURCE" redefined [enabled by default] + /usr/include/features.h:166:0: note: this is the location of the previous definition + ............................................................................ + Finished <<< rospack [ 11.7 seconds ] + ... + +Note that the first line displays the path to the interleaved log file, which persists until the build space is cleaned. +Additionally, if a package fails, the output to ``stderr`` is printed under the ``Errors`` header. + +.. code-block:: none + + ____________________________________________________________________________ + Errors << catkin_pkg_make_err:make /home/jbohren/ws/catkin_tools_test_ws/build/_logs/catkin_pkg_make_err/build.make.062.log + /home/jbohren/ws/catkin_tools_test_ws/src/catkin_pkg_make_err/main.cpp: In function ‘int main(int, char**)’: + /home/jbohren/ws/catkin_tools_test_ws/src/catkin_pkg_make_err/main.cpp:3:3: error: expected ‘,’ or ‘;’ before ‘return’ + make[2]: *** [CMakeFiles/main.dir/main.cpp.o] Error 1 + make[1]: *** [CMakeFiles/main.dir/all] Error 2 + make: *** [all] Error 2 + ............................................................................ + Failed << catkin_pkg_make_err:make [ Exited with code 2 ] + +All of the messages from the underlying jobs can be shown when using the +``-v`` or ``--verbose`` option. This will print the normal messages when a +build job starts and finishes as well as the interleaved output to ``stdout`` +and ``stderr`` from each build command in a block. - [catkin]: ==> '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/local/bin/cmake /path/to/my_catkin_ws/src/catkin -DCATKIN_DEVEL_PREFIX=/path/to/my_catkin_ws/devel/catkin -DCMAKE_INSTALL_PREFIX=/path/to/my_catkin_ws/install' in '/path/to/my_catkin_ws/build/catkin' - -- The C compiler identification is Clang 5.0.0 - -- The CXX compiler identification is Clang 5.0.0 - -- Check for working C compiler: /usr/bin/cc - -- Check for working C compiler: /usr/bin/cc -- works +.. code-block:: none + + Starting >>> genmsg + Starting >> genmsg:mkdir + Finished << genmsg:mkdir + Starting >> genmsg:envgen + Finished << genmsg:envgen + Starting >> genmsg:cmake + Subprocess > genmsg:cmake `cd /path/to/my_catkin_ws/build/genmsg && /path/to/my_catkin_ws/build/genmsg/build_env.sh /usr/bin/cmake /path/to/my_catkin_ws/src/genmsg --no-warn-unused-cli -DCATKIN_DEVEL_PREFIX=/path/to/my_catkin_ws/devel -DCMAKE_INSTALL_PREFIX=/path/to/my_catkin_ws/install` + Output << genmsg:cmake /path/to/my_catkin_ws/build/_logs/genmsg/build.cmake.000.log + Not searching for unused variables given on the command line. + Re-run cmake no build system arguments + -- The C compiler identification is GNU + -- The CXX compiler identification is GNU + -- Check for working C compiler: /usr/bin/gcc + -- Check for working C compiler: /usr/bin/gcc -- works -- Detecting C compiler ABI info -- Detecting C compiler ABI info - done -- Check for working CXX compiler: /usr/bin/c++ -- Check for working CXX compiler: /usr/bin/c++ -- works -- Detecting CXX compiler ABI info -- Detecting CXX compiler ABI info - done - -- Using CATKIN_DEVEL_PREFIX: /path/to/my_catkin_ws/devel/catkin - -- Using CMAKE_PREFIX_PATH: /path/to/my_catkin_ws/install - -- This workspace overlays: /path/to/my_catkin_ws/install - -- Found PythonInterp: /usr/bin/python (found version "2.7.5") + -- Using CATKIN_DEVEL_PREFIX: /path/to/my_catkin_ws/devel + -- Using CMAKE_PREFIX_PATH: /path/to/my_catkin_ws/smach/devel;/opt/ros/hydro + -- This workspace overlays: /path/to/my_catkin_ws/smach/devel;/opt/ros/hydro + -- Found PythonInterp: /usr/bin/python (found version "2.7.3") -- Using PYTHON_EXECUTABLE: /usr/bin/python -- Python version: 2.7 - -- Using default Python package layout - -- Found PY_em: /Library/Python/2.7/site-packages/em.pyc + -- Using Debian Python package layout -- Using CATKIN_ENABLE_TESTING: ON -- Call enable_testing() - -- Using CATKIN_TEST_RESULTS_DIR: /path/to/my_catkin_ws/build/catkin/test_results - -- Found gtest: gtests will be built - -- catkin 0.5.86 + -- Using CATKIN_TEST_RESULTS_DIR: /path/to/my_catkin_ws/build/genmsg/test_results + -- Looking for include files CMAKE_HAVE_PTHREAD_H + -- Looking for include files CMAKE_HAVE_PTHREAD_H - found + -- Looking for pthread_create in pthreads + -- Looking for pthread_create in pthreads - not found + -- Looking for pthread_create in pthread + -- Looking for pthread_create in pthread - found + -- Found Threads: TRUE + -- Found gtest sources under '/usr/src/gtest': gtests will be built + -- catkin 0.5.90 -- Configuring done -- Generating done - -- Build files have been written to: /path/to/my_catkin_ws/build/catkin - [catkin]: <== '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/local/bin/cmake /path/to/my_catkin_ws/src/catkin -DCATKIN_DEVEL_PREFIX=/path/to/my_catkin_ws/devel/catkin -DCMAKE_INSTALL_PREFIX=/path/to/my_catkin_ws/install' finished with return code '0' + -- Build files have been written to: /path/to/my_catkin_ws/build/genmsg + Finished << genmsg:cmake + Starting >> genmsg:make + Subprocess > genmsg:make `cd /path/to/my_catkin_ws/build/genmsg && /usr/bin/make --jobserver-fds=3,4 -j` + Output << genmsg:make /path/to/my_catkin_ws/build/_logs/genmsg/build.make.000.log + /usr/bin/cmake -H/path/to/my_catkin_ws/src/genmsg -B/path/to/my_catkin_ws/build/genmsg --check-build-system CMakeFiles/Makefile.cmake 0 + /usr/bin/cmake -E cmake_progress_start /path/to/my_catkin_ws/build/genmsg/CMakeFiles /path/to/my_catkin_ws/build/genmsg/CMakeFiles/progress.marks + /usr/bin/make -f CMakeFiles/Makefile2 all + make[1]: Entering directory `/path/to/my_catkin_ws/build/genmsg' + make[1]: Nothing to be done for `all'. + make[1]: Leaving directory `/path/to/my_catkin_ws/build/genmsg' + /usr/bin/cmake -E cmake_progress_start /path/to/my_catkin_ws/build/genmsg/CMakeFiles 0 + Finished << genmsg:make + Finished <<< genmsg [ 2.0 seconds ] + +Build Summary +------------- + +At the end of each build, a brief build summary is printed to guarantee that +anomalies aren't missed. This summary displays the total runtime, the number +of successful jobs, the number of jobs which produced warnings, and the +number of jobs which weren't attempted due to failed dependencies. - [catkin]: ==> '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/bin/make -j4 -l4' in '/path/to/my_catkin_ws/build/catkin' - [catkin]: <== '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/bin/make -j4 -l4' finished with return code '0' +.. code-block:: none - [catkin]: ==> '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/bin/make install' in '/path/to/my_catkin_ws/build/catkin' - Install the project... - -- Install configuration: "" - ... truncated for brevity - [catkin]: <== '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/bin/make install' finished with return code '0' + [build] Runtime: 1.9 seconds total. + [build] Summary: 4 of 7 jobs completed. + [build] Warnings: None. + [build] Abandoned: 1 jobs were abandoned. + [build] Failed: 2 jobs failed. - Finished <== catkin [ 3.4 seconds ] +Building Subsets of Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Consider a Catkin workspace with a **source space** populated with the following Catkin packages which have yet to be built: -.. note:: +.. code-block:: bash - The printing of these command outputs maybe be interleaved with commands - from other package builds if more than one package is being built at the - same time. + $ pwd + /tmp/path/to/my_catkin_ws -If you want to see the output from commands streaming to the screen, then you -can use the ``-i`` or ``--interleave`` option. This option will cause the -output from commands to be pushed to the screen immediately, instead of -buffering until the command finishes. This ends up being pretty confusing, so -when interleaved output is used ``catkin build`` prefixes each line with -``[]:`` like this: + $ ls ./* + ./src: + catkin console_bridge genlisp genpy + message_runtime ros_comm roscpp_core std_msgs + common_msgs gencpp genmsg message_generation + ros ros_tutorials rospack -.. code-block:: none - [roscpp_traits]: ==> '/Users/william/my_catkin_ws/build/roscpp_traits/build_env.sh /usr/bin/make cmake_check_build_system' in '/Users/william/my_catkin_ws/build/roscpp_traits' - [ros_tutorials]: -- The CXX compiler identification is Clang 5.0.0 - [ros_tutorials]: -- Check for working C compiler: /usr/bin/cc - [roscpp_traits]: ==> '/Users/william/my_catkin_ws/build/roscpp_traits/build_env.sh /usr/bin/make -j4 -l4' in '/Users/william/my_catkin_ws/build/roscpp_traits' - [rosbuild]: ==> '/Users/william/my_catkin_ws/build/rosbuild/build_env.sh /usr/bin/make -j4 -l4' in '/Users/william/my_catkin_ws/build/rosbuild' - [rosclean]: -- The C compiler identification is Clang 5.0.0 - [ros_tutorials]: -- Check for working C compiler: /usr/bin/cc -- works - [ros_tutorials]: -- Detecting C compiler ABI info - [rosclean]: -- The CXX compiler identification is Clang 5.0.0 - [rosclean]: -- Check for working C compiler: /usr/bin/cc +Building Specific Packages +-------------------------- -.. note:: +In addition to the usage above, the ``--dry-run`` option will show what the behavior of ``catkin build`` will be with various other options. +For example, the following will happen when you specify a single package to build: + +.. code-block:: bash + + $ catkin build roscpp_tutorials --dry-run + .... + Found '36' packages in 0.1 seconds. + Packages to be built: + - catkin (catkin) + - genmsg (catkin) + - gencpp (catkin) + - genlisp (catkin) + - genpy (catkin) + - console_bridge (cmake) + - cpp_common (catkin) + - message_generation (catkin) + - message_runtime (catkin) + - rosbuild (catkin) + - roscpp_traits (catkin) + - roslang (catkin) + - rospack (catkin) + - roslib (catkin) + - rostime (catkin) + - roscpp_serialization (catkin) + - rosunit (catkin) + - rosconsole (catkin) + - std_msgs (catkin) + - rosgraph_msgs (catkin) + - xmlrpcpp (catkin) + - roscpp (catkin) + - roscpp_tutorials (catkin) + Total packages: 23 + +As shown above, only 23 packages (``roscpp_tutorials`` and its dependencies), +of the total 36 packages would be built. + +Context-Aware Building +---------------------- + +In addition to building all packages or specified packages with various dependency requirements, ``catkin build`` can also determine the package containing the current working directory. +This is equivalent to specifying the name of the package on the command line, and is done by passing the ``--this`` option to ``catkin build`` like the following: + +.. code-block:: bash + + $ cd /tmp/path/to/my_catkin_ws/src/roscpp_tutorials + $ catkin build --this --dry-run + .... + Found '36' packages in 0.0 seconds. + Packages to be built: + - roscpp_tutorials (catkin) + Total packages: 1 + +Skipping Packages +----------------- + +Suppose you built every package up to ``roscpp_tutorials``, but that package had a build error. +After fixing the error, you could run the same build command again, but the ``build`` verb provides an option to save time in this situation. +If re-started from the beginning, none of the products of the dependencies of ``roscpp_tutorials`` would be re-built, but it would still take some time for the underlying byuildsystem to verify that for each package. + +Those checks could be skipped, however, by jumping directly to a given package. +You could use the ``--start-with`` option to continue the build where you left off after fixing the problem. (The following example uses the ``--dry-run`` option again to preview the behavior): + +.. code-block:: bash + + $ catkin build roscpp_tutorials --start-with roscpp_tutorials --dry-run + .... + Found '36' packages in 0.0 seconds. + Packages to be built: + (skip) catkin (catkin) + (skip) genmsg (catkin) + (skip) gencpp (catkin) + (skip) genlisp (catkin) + (skip) genpy (catkin) + (skip) console_bridge (cmake) + (skip) cpp_common (catkin) + (skip) message_generation (catkin) + (skip) message_runtime (catkin) + (skip) rosbuild (catkin) + (skip) roscpp_traits (catkin) + (skip) roslang (catkin) + (skip) rospack (catkin) + (skip) roslib (catkin) + (skip) rostime (catkin) + (skip) roscpp_serialization (catkin) + (skip) rosunit (catkin) + (skip) rosconsole (catkin) + (skip) std_msgs (catkin) + (skip) rosgraph_msgs (catkin) + (skip) xmlrpcpp (catkin) + (skip) roscpp (catkin) + ------ roscpp_tutorials (catkin) + Total packages: 23 - When you use ``-p 1`` and ``-v`` at the same time, ``-i`` is implicitly added. +However, you should be careful when using the ``--start-with`` option, as ``catkin build`` will assume that all dependencies leading up to that package have already been successfully built. +If you're only interested in building a *single* package in a workspace, you can also use the ``--no-deps`` option along with a package name. +This will skip all of the package's dependencies, build the given package, and then exit. + +.. code-block:: bash + + $ catkin build roscpp_tutorials --no-deps roscpp_tutorials --dry-run + .... + Found '36' packages in 0.0 seconds. + Packages to be built: + - roscpp_tutorials (catkin) + Total packages: 1 -Running Tests Built in a Workspace -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Building and Running Tests +^^^^^^^^^^^^^^^^^^^^^^^^^^ Running tests for a given package typically is done by invoking a special ``make`` target like ``test`` or ``run_tests``. catkin packages all define the ``run_tests`` target which aggregates all types of tests and runs them together. @@ -533,94 +527,56 @@ So if you want to check for failing tests, use the ``catkin_test_results`` comma The result code will be non-zero unless all tests passed. -Building With Warnings -^^^^^^^^^^^^^^^^^^^^^^ - -It can sometimes be useful to compile with additional warnings enabled across your whole catkin workspace. -To achieve this, use a command similar to this: - -.. code-block:: bash - - $ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter" - -This command passes the ``-DCMAKE_C_FLAGS=...`` arugment to all invocations of ``cmake``. - -Debugging Build Errors -^^^^^^^^^^^^^^^^^^^^^^ - -As mentioned above, by default the output from each build is optimistically -hidden to give a clean overview of the workspace build, but when there is a -problem with a build a few things happen. -First, the package with a failure prints the failing command's output to the -screen between some enclosing lines: - -.. code-block:: none +Advanced Options +^^^^^^^^^^^^^^^^ - [rospack]: ==> '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make -j4 -l4' in '/path/to/my_catkin_ws/build/rospack' - [ 66%] Built target rospack - make[1]: *** [CMakeFiles/rosstackexe.dir/all] Interrupt: 2 - make[1]: *** [CMakeFiles/rospackexe.dir/all] Interrupt: 2 - make: *** [all] Interrupt: 2 - [rospack]: <== '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make -j4 -l4' failed with return code '-2' +Temporarily Changing Build Flags +-------------------------------- -And the status line is updated to reflect that that package has run into an -issue by placing a ``!`` in front of it: +While the build configuratoin flags are set and stored in the build context, +it's possible to temporarily override or augment them when using the ``build`` +verb. -.. code-block:: none - - [build - 1.7] [!cpp_common] [!rospack] [genlisp - 0.3] [1/1 Active | 10/23 Completed] +.. code-block:: bash -Then the ``catkin build`` command waits for the rest of the currently still building packages to finish -(without starting new package builds) and then summarizes the errors for you: + $ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter" -.. code-block:: none +Building With Warnings +---------------------- - [build] There were '2' errors: +It can sometimes be useful to compile with additional warnings enabled across your whole catkin workspace. +To achieve this, use a command similar to this: - Failed to build package 'cpp_common' because the following command: +.. code-block:: bash - # Command run in directory: /path/to/my_catkin_ws/build/cpp_common - /path/to/my_catkin_ws/build/cpp_common/build_env.sh /usr/bin/make -j4 -l4 + $ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter" - Exited with return code: -2 +This command passes the ``-DCMAKE_C_FLAGS=...`` arugment to all invocations of ``cmake``. - Failed to build package 'rospack' because the following command: - # Command run in directory: /path/to/my_catkin_ws/build/rospack - /path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make -j4 -l4 +Configuring Build Jobs +---------------------- - Exited with return code: -2 - Build summary: - Successful catkin - Successful genmsg - ... - Failed cpp_common - Failed rospack - Not built roscpp_serialization - Not built roscpp - ... +By default ``catkin build`` on a computer with ``N`` cores will build up to +``N`` packages in parallel and will distribute ``N`` ``make`` jobs among them +using an internal jobserver. If your platform doesn't support jobserver +scheduling, ``catkin build`` will pass ``-jN -lN`` to ``make`` for each package. -Packages marked as `Not built` were requested, but not yet built because catkin stopped due to failed packages. +You can control the maximum number of packages allowed to build in parallel by +using the ``-p`` or ``--parallel-packages`` option and you can change the +number of ``make`` jobs available with the ``-j`` or ``--jobs`` option. -To try to build as many requested packages as possible (instead of stopping after the first package failed), -you can pass the ``--continue-on-failure`` option. Then the ``catkin build`` command will then continue building packages whose dependencies built successfully +By default, these jobs options aren't passed to the underlying ``make`` +command. To disable the jobserver, you can use the ``--no-jobserver`` option, and +you can pass flags directly to ``make`` with the ``--make-args`` option. -If you don't want to scroll back up to find the error amongst the other output, -you can ``cat`` the whole build log out of the ``build_logs`` folder in the -**build space**: +.. note:: -.. code-block:: bash + Jobs flags (``-jN`` and/or ``-lN``) can be passed directly to ``make`` by + giving them to ``catkin build``, but other ``make`` arguments need to be + passed to the ``--make-args`` option. - $ cat build/build_logs/rospack.log - [rospack]: ==> '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make cmake_check_build_system' in '/path/to/my_catkin_ws/build/rospack' - [rospack]: <== '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make cmake_check_build_system' finished with return code '0' - [rospack]: ==> '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make -j4 -l4' in '/path/to/my_catkin_ws/build/rospack' - [ 66%] Built target rospack - make[1]: *** [CMakeFiles/rosstackexe.dir/all] Interrupt: 2 - make[1]: *** [CMakeFiles/rospackexe.dir/all] Interrupt: 2 - make: *** [all] Interrupt: 2 - [rospack]: <== '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make -j4 -l4' failed with return code '-2' Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/verbs/catkin_find.rst b/docs/verbs/catkin_locate.rst similarity index 95% rename from docs/verbs/catkin_find.rst rename to docs/verbs/catkin_locate.rst index dc6a0c09..d954bcd9 100644 --- a/docs/verbs/catkin_find.rst +++ b/docs/verbs/catkin_locate.rst @@ -1,5 +1,5 @@ -``catkin locate`` -- Find Workspace Locations -=========================================== +``catkin locate`` -- Locate Directories +======================================= The ``locate`` verb can be used to locate important locations in the workspace such as the active ``source``, ``build``, ``devel``, and ``install`` spaces, and package From 4a91a4bed4f571a8779f2911b98240046015d925 Mon Sep 17 00:00:00 2001 From: Jonathan Bohren Date: Thu, 17 Dec 2015 17:53:56 -0500 Subject: [PATCH 02/10] doc: Updating CMake build type build stages --- docs/build_types.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/build_types.rst b/docs/build_types.rst index 51d55f77..ab04a1e9 100644 --- a/docs/build_types.rst +++ b/docs/build_types.rst @@ -33,7 +33,7 @@ Build Stages ============== ============ ================================================== ``mkdir`` | Create package build space if it doesn't exist. ---------------------------- -------------------------------------------------- - ``envgen`` | Generate environment setup file for building. + ``buildenvgen`` | Generate environment setup file for building. ---------------------------- -------------------------------------------------- ``cmake`` ``check`` | Run CMake configure step **once** for the | first build and the ``cmake_check_build_system`` @@ -48,6 +48,12 @@ Build Stages ---------------------------- -------------------------------------------------- ``install`` `optional` | Run the ``install`` target after building. | This is only done with the ``--install`` option. +---------------------------- -------------------------------------------------- + ``setupgen`` | Generate a ``setup.sh`` file to "source" the \ + | result space. +---------------------------- -------------------------------------------------- + ``envgen`` | Generate an ``env.sh`` file for loading the \ + | result space's environment. ============================ ================================================== CMake From 6806ce336547d8552da3ef3cae4766ee4a9bd574 Mon Sep 17 00:00:00 2001 From: Jonathan Bohren Date: Tue, 26 Jan 2016 15:13:26 -0500 Subject: [PATCH 03/10] docs: Adding migration, mem-limit, env-caching docs --- docs/index.rst | 13 +- docs/migration.rst | 320 +++++++++++++++++++++++++++++++++++ docs/troubleshooting.rst | 7 + docs/verbs/catkin_build.rst | 84 +++++++-- docs/verbs/catkin_config.rst | 58 +++++-- 5 files changed, 451 insertions(+), 31 deletions(-) create mode 100644 docs/migration.rst diff --git a/docs/index.rst b/docs/index.rst index 7405d218..0b1e3d04 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,9 +10,10 @@ Catkin Command Line Tools Installing quick_start - mechanics - config_summary cheat_sheet + Migration Guide + mechanics + Workspace Configuration build_types Troubleshooting @@ -64,9 +65,15 @@ This Python package provides command line tools for working with the catkin meta .. note:: This is the documentation for the ``catkin`` command-line tool and **not** - the Catkin package specification documentation. For documentation on writing + the Catkin CMake documentation. For documentation on creating catkin packages, see: http://docs.ros.org/api/catkin/html/ +.. note:: + + Users of ``catkin_make`` and ``catkin_make_isolated`` should go to the + :doc:`Migration Guide ` for help transitioning to ``catkin + build``. + The ``catkin`` command ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/migration.rst b/docs/migration.rst new file mode 100644 index 00000000..8245a963 --- /dev/null +++ b/docs/migration.rst @@ -0,0 +1,320 @@ +Migrating from catkin_make +========================== + +Important Distinctions between ``catkin_make`` and ``catkin build`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Unlike ``catkin_make``, the ``catkin`` command-line tool is not just a thin +wrapper around a ``CMake`` use pattern. The ``catkin build`` command builds +each package in a workspace's source space *in isolation* in order to prevent +buildtime cross-talk. As such, in its simplest use, ``catkin build`` is like a +parallelized version of ``catkin_make_isolated``. While there are many more +features in ``catkin_tools`` described in the rest of the documentation, this +chapter provides details on how to switch from using ``catkin_make`` or +``catkin_make_isolated``. + +Operational Differences +^^^^^^^^^^^^^^^^^^^^^^^ + +- ``catkin_tools`` has no "top-level" ``CMakeLists.txt`` file. The **source + space** simply contains a collection of packages. If you have been modifying + this ``CMakeLists.txt`` file, those modifications will be ignored. +- Each package in a ``catkin_tools`` workspace has its own isolated build space. +- ``catkin build`` can be run from any directory under the workspace root +- ``catkin config`` stores many workspace configuration options which needed to + be passed to each call of ``catkin_make`` +- ``catkin build`` can build plain CMake packages if they have ``package.xml`` + files +- Packages built with ``catkin build`` can not access variables defined in + other Catkin packages in the same workspace. +- Packages no longer need to define target dependencies on ROS messages built + in other packages. All targets in a dependency are guaranteed to have been + built before the current package. +- ``catkin_tools`` and ``catkin_make`` can use the same source space, but they + must use different build, devel, and install spaces. + +IDE Integration +^^^^^^^^^^^^^^^ + +Since all packages are built in isolation with ``catkin build``, you can't rely +on CMake's IDE integration to generate a single project for your entire workspace. + +.. _migration-troubleshooting: + +Migration Troubleshooting +^^^^^^^^^^^^^^^^^^^^^^^^^ + +When migrating from ``catkin_make`` to catkin build, the most common problems +come from Catkin packages taking advantge of package cross-talk in the CMake +configuration stage. + +Many Catkin packages implicitly rely on other packages in a workspace to +declare and find dependencies. When switcing from ``catkin_make``, users +will often discover these bugs. + +Common Issues +------------- + +Unknown CMake command "catkin_package" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If ``find_package(catkin REQUIRED ...)`` isn't called, then the +``catkin_package()`` macro will not be available. If such a package builds with +``catkin_make``, it's because it's relying on another package in the same +workspace to do this work. + +Compilation Errors (Missing Headers) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Compilation errors can occur if required headers are not found. If +your package includes headers from ``${catkin_INCLUDE_DIRS}``, make sure *that* +package is finding the right Catkin packages in ``find_package(catkin +COMPONENTS ...)``. + +If your package includes headers from other libraries, make sure those +libraries are found and those CMake variables are defined. + +Linker Errors (Undefined References) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Linker errors are due to targets not being linked to required libraries. If +your target links against ``${catkin_LIBRARIES}``, make sure *that* package +is finding the right Catkin packages in ``find_package(catkin COMPONENTS ...)``. + +If your target links against other libraries, make sure those libraries are +found and those CMake variables are defined. + +- https://github.com/catkin/catkin_tools/issues/228 + +Targets Not Being Built +~~~~~~~~~~~~~~~~~~~~~~~ + +It is critical for Catkin-based packages to call ``catkin_package()`` before +**any** targets are defined. Otherwise your targets will not be built into the +**devel space**. Previously with ``catkin_make``, as long as some package +called ``catkin_package()`` before your package was configured, the appropriate +target destinations were defined. + +- https://github.com/catkin/catkin_tools/issues/220 + +Compiler Options Aren't Correct +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Your program might fail to build or fail to run due to incorrect compiler +options. Sometimes these compiler options are needed to use a dependency, but +aren't made available to the dependant package. + +With ``catkin_make``, if a package sets certain compiler options, such as: + +.. code-block:: cmake + + set(CMAKE_CXX_FLAGS "-std=c++ ${CMAKE_CXX_FLAGS}") + +These options will be set for every package in the topological sort which is +built after it, even packages which don't depend on it. + +With ``catkin build``, however, these effects are isolated, so even the packages +that need these options will not get them. The ``catkin_package()`` macro already +provides options for exporting libraries and include directories, but it does not +have an option for CMake variables. + +To export such settings (or even execute code), the ``CFG_EXTRAS`` option +must be used with an accompanying CMake file. For more information on this option, +see `the catkin_package() documentation `_. + +- https://github.com/catkin/catkin_tools/issues/210 +- https://github.com/carpe-noctem-cassel/cnc-msl/pull/1 + +Uncommon Issues +--------------- + +Exporting Build Utilities +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some Catkin packages provide build tools at configuration time, like scripts +for generating code or downloading resources from the internet. These +packages need to export absolute paths to such tools both when used in a +workspace and when installed. + +For example, when using in a source space, the build tools from package +``my_build_util`` would be found at ``${CMAKE_CURRENT_SOURCE_DIR}/cmake``, but +when installed, they would be found in ``${my_build_util_DIR}``. + +With ``catkin_make``, the path to these tools could be set to either the source +or install space in the provider package just by setting a CMake variable, which +would be "leaked" to all subsequently built packages. + +With ``catkin build``, these paths need to be properly exported with +``CFG_EXTRAS``. A way to do this that works both out of a workspace and install +is shown below: + +.. code-block:: cmake + :caption: my_build_util-extras.cmake.em + + # generated from stdr_common/cmake/stdr_common-extras.cmake.em + + @[if DEVELSPACE]@ + # set path to source space + set(my_build_util_EXTRAS_DIR "@(CMAKE_CURRENT_SOURCE_DIR)/cmake") + @[else]@ + # set path to installspace + set(my_build_util_EXTRAS_DIR "${my_build_util_DIR}") + @[end if]@ + + +Exporting Non-Standard Library Output Locations or Prefixes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some users may choose to build library targets with non-standard output +locations or prefixes. However, the normal ``catkin_package()`` macro +cannot export libraries with such paths across packages. + +Again, we can use the ``CFG_EXTRAS`` option to append the special library to +the ``${PROJECT_NAME}_LIBRARIES`` variable that ``catkin_package()`` exports to +other packages. + +.. code-block:: cmake + :caption: CMakeLists.txt + + catkin_package( + ... + LIBRARIES # NOTE: Not specified here, but in extras file + CFG_EXTRAS my-extras.cmake + ) + + set_target_properties( + ${PROJECT_NAME} PROPERTIES + PREFIX "" + LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION} + ) + +.. code-block:: cmake + :caption: my.cmake.in + + find_library(@PROJECT_NAME@_LIBRARY + NAMES @PROJECT_NAME@ + PATHS "${@PROJECT_NAME@_DIR}/../../../@CATKIN_GLOBAL_LIB_DESTINATION@/" + NO_DEFAULT_PATH) + + if(@PROJECT_NAME@_LIBRARY) + # Multiple CMake projects case (i.e. 'catkin build'): + # - The target has already been built when its dependencies require it + # - Specify full path to found library + list(APPEND @PROJECT_NAME@_LIBRARIES ${@PROJECT_NAME@_LIBRARY}) + else() + # Single CMake project case (i.e. 'catkin_make'): + # - The target has not been built when its dependencies require it + # - Specify target name only + list(APPEND @PROJECT_NAME@_LIBRARIES @PROJECT_NAME@) + endif() + + +- https://github.com/catkin/catkin_tools/issues/128 +- http://answers.ros.org/question/201036/how-can-catkin-find-ros-libraries-in-non-standard-locations/?answer=209923#post-id-209923 + + +Controlling Python Version +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On some platforms, there are multiple versions of Python, and Catkin's +internal setup file generation might pick the wrong one. For ``catkin_make``, +this is sometimes solved on a given platform by creating a shell alias which +sets the ``PYTHON_EXECUTABLE`` CMake variable. + +For ``catkin build``, however, you can create a *verb alias* like the one +below, which overrides the default behavior of ``catkin build`` even in new +workspaces. + +.. code-block:: yaml + + build: build -DPYTHON_EXECUTABLE=/usr/bin/python2.7 + +See :doc:`Verb Aliasing ` for more details. + +- https://github.com/catkin/catkin_tools/issues/166 + +CLI Comparison with ``catkin_make`` and ``catkin_make_isolated`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Below are tables mapping ``catkin_make`` and ``catkin_make_isolated`` arguments +into ``catkin`` arguments. Note that some ``catkin_make`` options can only be +achived with the ``catkin config`` verb. + +================================================= ============================================ + catkin_make ... catkin ... +================================================= ============================================ + ``-C PATH`` ``-w PATH [build | config | ...]`` +------------------------------------------------- -------------------------------------------- + ``--source PATH`` ``config --source-space PATH`` [1]_ +------------------------------------------------- -------------------------------------------- + ``--build PATH`` ``config --build-space PATH`` [1]_ +------------------------------------------------- -------------------------------------------- + ``--use-ninja`` *not yet available* +------------------------------------------------- -------------------------------------------- + ``--force-cmake`` ``build --force-cmake`` +------------------------------------------------- -------------------------------------------- + ``--pkg PKG [PKG ...]`` ``build --no-deps PKG [PKG ...]`` +------------------------------------------------- -------------------------------------------- + ``--only-pkg-with-deps PKG [PKG ...]`` ``build PKG [PKG ...]`` +------------------------------------------------- -------------------------------------------- + ``--cmake-args ARG [ARG ...]`` ``build --cmake-args ARG [ARG ...]`` [2]_ +------------------------------------------------- -------------------------------------------- + ``--make-args ARG [ARG ...]`` ``build --make-args ARG [ARG ...]`` [2]_ +------------------------------------------------- -------------------------------------------- + ``--override-build-tool-check`` ``build --override-build-tool-check`` +------------------------------------------------- -------------------------------------------- + ``ARG [ARG ...]`` ``build --make-args ARG [ARG ...]`` +------------------------------------------------- -------------------------------------------- + ``install`` ``config --install`` [1]_ +------------------------------------------------- -------------------------------------------- + ``-DCATKIN_DEVEL_PREFIX=PATH`` ``config --devel-space PATH`` [1]_ +------------------------------------------------- -------------------------------------------- + ``-DCATKIN_INSTALL_PREFIX=PATH`` ``config --install-space PATH`` [1]_ +------------------------------------------------- -------------------------------------------- + ``-DCATKIN_WHITELIST_PACKAGES="PKG[;PKG ...]"`` ``config --whitelist PKG [PKG ...]`` [1]_ +================================================= ============================================ + + +======================================== ============================================ + catkin_make_isolated ... catkin ... +======================================== ============================================ + ``-C PATH`` ``-w PATH [build | config | ...]`` +---------------------------------------- -------------------------------------------- + ``--source PATH`` ``config --source-space PATH`` [1]_ +---------------------------------------- -------------------------------------------- + ``--build PATH`` ``config --build-space PATH`` [1]_ +---------------------------------------- -------------------------------------------- + ``--devel PATH`` ``config --devel-space PATH`` [1]_ +---------------------------------------- -------------------------------------------- + ``--merge`` ``config --devel-layout merged`` [1]_ +---------------------------------------- -------------------------------------------- + ``--install-space PATH`` ``config --install-space PATH`` [1]_ +---------------------------------------- -------------------------------------------- + ``--use-ninja`` *not yet available* +---------------------------------------- -------------------------------------------- + ``--install`` ``config --install`` [1]_ +---------------------------------------- -------------------------------------------- + ``--force-cmake`` ``build --force-cmake`` +---------------------------------------- -------------------------------------------- + ``--no-color`` ``build --no-color`` +---------------------------------------- -------------------------------------------- + ``--pkg PKG [PKG ...]`` ``build --no-deps PKG [PKG ...]`` +---------------------------------------- -------------------------------------------- + ``--from-pkg PKG`` ``build --start-with PKG`` +---------------------------------------- -------------------------------------------- + ``--only-pkg-with-deps PKG [PKG ...]`` ``build PKG [PKG ...]`` +---------------------------------------- -------------------------------------------- + ``--cmake-args ARG [ARG ...]`` ``build --cmake-args ARG [ARG ...]`` [2]_ +---------------------------------------- -------------------------------------------- + ``--make-args ARG [ARG ...]`` ``build --make-args ARG [ARG ...]`` [2]_ +---------------------------------------- -------------------------------------------- + ``--catkin-make-args ARG [ARG ...]`` ``build --catkin-make-args ARG [ARG ...]`` [2]_ +---------------------------------------- -------------------------------------------- + ``--override-build-tool-check`` ``build --override-build-tool-check`` +======================================== ============================================ + +.. [1] These options require a subsequent call to ``catkin build``, and the options + will continue to persist until changed. +.. [2] These options, if passed to ``catkin build`` only affect that + invocation. If passed to ``catkin config``, they will persist to + subseqent calls to ``catkin build``. diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 1314e30e..918d7bdd 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -34,3 +34,10 @@ Packages Are Being Built Out of Order a package can't be found. - Run ``catkin list --deps /path/to/ws/src`` to list the dependencies of each package and look for errors. + + +Migration Problems +^^^^^^^^^^^^^^^^^^ + +For troubleshooting problems when migrating from ``catkin_make`` or +``catkin_make_isolated``, see :ref:`migration-troubleshooting`. diff --git a/docs/verbs/catkin_build.rst b/docs/verbs/catkin_build.rst index 1e276e6f..c12f1bb0 100644 --- a/docs/verbs/catkin_build.rst +++ b/docs/verbs/catkin_build.rst @@ -347,6 +347,9 @@ number of jobs which weren't attempted due to failed dependencies. [build] Abandoned: 1 jobs were abandoned. [build] Failed: 2 jobs failed. +A more detailed summary can also be printed, which lists the result for each +package in the workspace. + Building Subsets of Packages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Consider a Catkin workspace with a **source space** populated with the following Catkin packages which have yet to be built: @@ -578,20 +581,49 @@ you can pass flags directly to ``make`` with the ``--make-args`` option. passed to the ``--make-args`` option. +Configuring Memory Use +---------------------- + +In addition to CPU and load limits, ``catkin build`` can also limit the number of +running jobs based on the available memory, using the hidden ``--mem-limit`` flag. +This flag requires installing the Python ``psutil`` module and is useful on systems +without swap partitions or other situations where memory use needs to be limited. + +Memory is specified either by percent or by the number of bytes. + +For example, to specify that ``catkin build`` should not start additional parallel jobs +when 50% of the available memory is used, you could run: + +.. code-block:: bash + + $ catkin build --mem-limit 50% + +Alternatively, if it sohuld not start additional jobs when over 4GB of memory +is used, you can specifiy: + +.. code-block:: bash + + $ catkin build --mem-limit 4G + + Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: text usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE] - [--dry-run] [--this] [--no-deps] - [--start-with PKGNAME | --start-with-this | --continue-on-failure] - [--force-cmake] [--no-install-lock] [--save-config] - [--parallel-jobs PARALLEL_JOBS] - [--cmake-args ARG [ARG ...] | --no-cmake-args] - [--make-args ARG [ARG ...] | --no-make-args] - [--catkin-make-args ARG [ARG ...] | --no-catkin-make-args] - [--verbose] [--interleave-output] [--no-status] [--no-notify] + [--dry-run] [--get-env PKGNAME] [--this] [--no-deps] + [--unbuilt] [--start-with PKGNAME | --start-with-this] + [--continue-on-failure] [--force-cmake] [--pre-clean] + [--no-install-lock] [--save-config] [-j JOBS] + [-p PACKAGE_JOBS] [--jobserver | --no-jobserver] + [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...] + | --no-cmake-args] [--make-args ARG [ARG ...] | + --no-make-args] [--catkin-make-args ARG [ARG ...] | + --no-catkin-make-args] [--verbose] [--interleave-output] + [--no-status] [--summarize] [--no-summarize] + [--override-build-tool-check] + [--limit-status-rate LIMIT_STATUS_RATE] [--no-notify] [PKGNAME [PKGNAME ...]] Build one or more packages in a catkin workspace. This invokes `CMake`, @@ -610,6 +642,8 @@ Full Command-Line Interface profile) --dry-run, -n List the packages which will be built with the given arguments without building them. + --get-env PKGNAME Print the environment in which PKGNAME is built to + stdout. Packages: Control which packages get built. @@ -620,6 +654,7 @@ Full Command-Line Interface --this Build the package containing the current working directory. --no-deps Only build specified packages, not their dependencies. + --unbuilt Build packages which have yet to be built. --start-with PKGNAME Build a given package and those which depend on it, skipping any before it. --start-with-this Similar to --start-with, starting with the package @@ -633,17 +668,29 @@ Full Command-Line Interface Control the build behavior. --force-cmake Runs cmake explicitly for each catkin package. + --pre-clean Runs `make clean` before building each package. --no-install-lock Prevents serialization of the install steps, which is on by default to prevent file install collisions Config: - Parameters for the underlying buildsystem. + Parameters for the underlying build system. --save-config Save any configuration options in this section for the next build invocation. - --parallel-jobs PARALLEL_JOBS, --parallel PARALLEL_JOBS, -p PARALLEL_JOBS - Maximum number of packages which could be built in + -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across + active packages. (default is cpu count) + -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS + Maximum number of packages allowed to be built in parallel (default is cpu count) + --jobserver Use the internal GNU Make job server which will limit + the number of Make jobs across all active packages. + --no-jobserver Disable the internal GNU Make job server, and use an + external one (like distcc, for example). + --env-cache Re-use cached environment variables when re-sourcing a + resultspace that has been loaded at a different stage + in the task. + --no-env-cache Don't cache environment variables when re-sourcing the + same resultspace. --cmake-args ARG [ARG ...] Arbitrary arguments which are passes to CMake. It collects all of following arguments until a "--" is @@ -673,4 +720,17 @@ Full Command-Line Interface commands are running at the same time. --no-status Suppresses status line, useful in situations where carriage return is not properly supported. - --no-notify Suppresses system popup notification. + --summarize, --summary, -s + Adds a build summary to the end of a build; defaults + to on with --continue-on-failure, off otherwise + --no-summarize, --no-summary + Explicitly disable the end of build summary + --override-build-tool-check + use to override failure due to using differnt build + tools on the same workspace. + --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE + Limit the update rate of the status bar to this + frequency. Zero means unlimited. Must be positive, + default is 10 Hz. + --no-notify Suppresses system pop-up notification. + diff --git a/docs/verbs/catkin_config.rst b/docs/verbs/catkin_config.rst index f1ef1780..ba1893a7 100644 --- a/docs/verbs/catkin_config.rst +++ b/docs/verbs/catkin_config.rst @@ -209,6 +209,17 @@ To clear the blacklist, you can use the ``--no-blacklist`` option: Note that you can still build packages on the blacklist and whitelist by passing their names to ``catkin build`` explicitly. +Accelerated Building with Environment Caching +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each package is built in a special environment which is loaded from the +current workspace and any workspaces that the current workspace is extending. +If you are confident that your workspace's environment is not changing during +a build, you can tell ``catkin build`` to cache these environments with the +``--cache-env`` option. This has the effect of dramatically reducing build times +for workspaces where many packages are already built. + + Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -223,10 +234,12 @@ Full Command-Line Interface [-b BUILD_SPACE | --default-build-space] [-d DEVEL_SPACE | --default-devel-space] [-i INSTALL_SPACE | --default-install-space] - [-x SPACE_SUFFIX] [--isolate-devel | --merge-devel] + [-x SPACE_SUFFIX] + [--merge-devel | --link-devel | --isolate-devel] [--install | --no-install] - [--isolate-install | --merge-install] - [--parallel-jobs PARALLEL_JOBS] + [--isolate-install | --merge-install] [-j JOBS] + [-p PACKAGE_JOBS] [--jobserver | --no-jobserver] + [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...] | --no-cmake-args] [--make-args ARG [ARG ...] | --no-make-args] [--catkin-make-args ARG [ARG ...] | @@ -303,10 +316,13 @@ Full Command-Line Interface Devel Space: Options for configuring the structure of the devel space. - --isolate-devel Build products from each catkin package into isolated - devel spaces. --merge-devel Build products from each catkin package into a single merged devel spaces. + --link-devel Build products from each catkin package into isolated + spaces, then symbolically link them into a merged + devel space. + --isolate-devel Build products from each catkin package into isolated + devel spaces. Install Space: Options for configuring the structure of the install space. @@ -323,25 +339,35 @@ Full Command-Line Interface Build Options: Options for configuring the way packages are built. - --parallel-jobs PARALLEL_JOBS, --parallel PARALLEL_JOBS, -p PARALLEL_JOBS - Maximum number of packages which could be built in + -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across + active packages. (default is cpu count) + -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS + Maximum number of packages allowed to be built in parallel (default is cpu count) + --jobserver Use the internal GNU Make job server which will limit + the number of Make jobs across all active packages. + --no-jobserver Disable the internal GNU Make job server, and use an + external one (like distcc, for example). + --env-cache Re-use cached environment variables when re-sourcing a + resultspace that has been loaded at a different stage + in the task. + --no-env-cache Don't cache environment variables when re-sourcing the + same resultspace. --cmake-args ARG [ARG ...] - Arbitrary arguments which are passes to CMake. It must - be passed after other arguments since it collects all - following options. + Arbitrary arguments which are passes to CMake. It + collects all of following arguments until a "--" is + read. --no-cmake-args Pass no additional arguments to CMake. --make-args ARG [ARG ...] - Arbitrary arguments which are passes to make.It must - be passed after other arguments since it collects all - following options. + Arbitrary arguments which are passes to make.It + collects all of following arguments until a "--" is + read. --no-make-args Pass no additional arguments to make (does not affect --catkin-make-args). --catkin-make-args ARG [ARG ...] Arbitrary arguments which are passes to make but only - for catkin packages.It must be passed after other - arguments since it collects all following options. + for catkin packages.It collects all of following + arguments until a "--" is read. --no-catkin-make-args Pass no additional arguments to make for catkin packages (does not affect --make-args). - From c107a125ee6f4467afbbf18a826c388cfb7ba84f Mon Sep 17 00:00:00 2001 From: Jonathan Bohren Date: Mon, 8 Feb 2016 09:23:39 -0500 Subject: [PATCH 04/10] docs: Numerous updates for #276 - updated build type stages - added scripts for recording examples - added scripts for capturing CLI interfaces to txt files - moved catkin tools history to specific history page - simplified index - updated build mechanics for new features - added migration guide with troubleshooting based on observed use cases - updated quick start with asciinemas - updated build with asciinemas - added env verb - added example resources to installation --- docs/build_types.rst | 2 - docs/examples/capture | 5 + docs/examples/failure_ws/0_init.bash | 3 + docs/examples/failure_ws/1_build_warning.bash | 2 + docs/examples/failure_ws/2_build_err.bash | 2 + .../src/catkin_pkg_cmake_err/CMakeLists.txt | 158 ++++++ .../src/catkin_pkg_cmake_err/package.xml | 50 ++ .../catkin_pkg_cmake_err/sub/CMakeLists.txt | 4 + .../src/catkin_pkg_cmake_warn/CMakeLists.txt | 158 ++++++ .../src/catkin_pkg_cmake_warn/package.xml | 50 ++ .../src/catkin_pkg_make_err/CMakeLists.txt | 156 +++++ .../src/catkin_pkg_make_err/main.cpp | 4 + .../src/catkin_pkg_make_err/package.xml | 50 ++ .../src/catkin_pkg_make_warn/CMakeLists.txt | 156 +++++ .../failure_ws/src/catkin_pkg_make_warn/a.out | Bin 0 -> 8376 bytes .../src/catkin_pkg_make_warn/grep-errors.txt | 2 + .../failure_ws/src/catkin_pkg_make_warn/main | Bin 0 -> 8376 bytes .../src/catkin_pkg_make_warn/main.cpp | 5 + .../src/catkin_pkg_make_warn/package.xml | 50 ++ docs/examples/quickstart_ws/0_quickstart.bash | 13 + docs/examples/quickstart_ws/1_prebuild.bash | 2 + .../quickstart_ws/1_prebuild.bash.out | 11 + docs/examples/quickstart_ws/2_postbuild.bash | 2 + .../quickstart_ws/2_postbuild.bash.out | 31 + .../examples/ros_tutorials_ws/0_checkout.bash | 7 + docs/examples/ros_tutorials_ws/1_init.bash | 2 + docs/examples/ros_tutorials_ws/2_dry_run.bash | 2 + docs/examples/ros_tutorials_ws/3_build.bash | 4 + docs/examples/ros_tutorials_ws/4_build_v.bash | 2 + docs/examples/ros_tutorials_ws/5_build_i.bash | 2 + .../ros_tutorials_ws/6_build_partial.bash | 2 + .../ros_tutorials_ws/7_build_this.bash | 4 + .../ros_tutorials_ws/8_build_start_with.bash | 2 + .../ros_tutorials_ws/9_build_no_deps.bash | 2 + docs/examples/slowrecord | 24 + docs/examples/slowrun | 81 +++ docs/history.rst | 127 +++++ docs/index.rst | 36 +- docs/mechanics.rst | 523 ++++++++++------- docs/migration.rst | 7 + docs/quick_start.rst | 158 ++---- docs/verbs/catkin_build.rst | 536 ++++-------------- docs/verbs/catkin_clean.rst | 35 +- docs/verbs/catkin_config.rst | 154 +---- docs/verbs/catkin_create.rst | 71 +-- docs/verbs/catkin_env.rst | 14 + docs/verbs/catkin_init.rst | 16 +- docs/verbs/catkin_list.rst | 22 +- docs/verbs/catkin_locate.rst | 40 +- docs/verbs/catkin_profile.rst | 81 +-- docs/verbs/cli/catkin_build.txt | 122 ++++ docs/verbs/cli/catkin_clean.txt | 35 ++ docs/verbs/cli/catkin_config.txt | 146 +++++ docs/verbs/cli/catkin_create.txt | 10 + docs/verbs/cli/catkin_create_pkg.txt | 55 ++ docs/verbs/cli/catkin_env.txt | 20 + docs/verbs/cli/catkin_init.txt | 11 + docs/verbs/cli/catkin_list.txt | 25 + docs/verbs/cli/catkin_locate.txt | 38 ++ docs/verbs/cli/catkin_profile.txt | 19 + docs/verbs/cli/catkin_profile_add.txt | 11 + docs/verbs/cli/catkin_profile_list.txt | 6 + docs/verbs/cli/catkin_profile_remove.txt | 7 + docs/verbs/cli/catkin_profile_rename.txt | 9 + docs/verbs/cli/catkin_profile_set.txt | 7 + docs/verbs/cli/dump_cli | 17 + setup.py | 1 + 67 files changed, 2235 insertions(+), 1174 deletions(-) create mode 100755 docs/examples/capture create mode 100755 docs/examples/failure_ws/0_init.bash create mode 100644 docs/examples/failure_ws/1_build_warning.bash create mode 100644 docs/examples/failure_ws/2_build_err.bash create mode 100644 docs/examples/failure_ws/src/catkin_pkg_cmake_err/CMakeLists.txt create mode 100644 docs/examples/failure_ws/src/catkin_pkg_cmake_err/package.xml create mode 100644 docs/examples/failure_ws/src/catkin_pkg_cmake_err/sub/CMakeLists.txt create mode 100644 docs/examples/failure_ws/src/catkin_pkg_cmake_warn/CMakeLists.txt create mode 100644 docs/examples/failure_ws/src/catkin_pkg_cmake_warn/package.xml create mode 100644 docs/examples/failure_ws/src/catkin_pkg_make_err/CMakeLists.txt create mode 100644 docs/examples/failure_ws/src/catkin_pkg_make_err/main.cpp create mode 100644 docs/examples/failure_ws/src/catkin_pkg_make_err/package.xml create mode 100644 docs/examples/failure_ws/src/catkin_pkg_make_warn/CMakeLists.txt create mode 100755 docs/examples/failure_ws/src/catkin_pkg_make_warn/a.out create mode 100644 docs/examples/failure_ws/src/catkin_pkg_make_warn/grep-errors.txt create mode 100755 docs/examples/failure_ws/src/catkin_pkg_make_warn/main create mode 100644 docs/examples/failure_ws/src/catkin_pkg_make_warn/main.cpp create mode 100644 docs/examples/failure_ws/src/catkin_pkg_make_warn/package.xml create mode 100755 docs/examples/quickstart_ws/0_quickstart.bash create mode 100755 docs/examples/quickstart_ws/1_prebuild.bash create mode 100644 docs/examples/quickstart_ws/1_prebuild.bash.out create mode 100644 docs/examples/quickstart_ws/2_postbuild.bash create mode 100644 docs/examples/quickstart_ws/2_postbuild.bash.out create mode 100644 docs/examples/ros_tutorials_ws/0_checkout.bash create mode 100644 docs/examples/ros_tutorials_ws/1_init.bash create mode 100644 docs/examples/ros_tutorials_ws/2_dry_run.bash create mode 100644 docs/examples/ros_tutorials_ws/3_build.bash create mode 100644 docs/examples/ros_tutorials_ws/4_build_v.bash create mode 100644 docs/examples/ros_tutorials_ws/5_build_i.bash create mode 100644 docs/examples/ros_tutorials_ws/6_build_partial.bash create mode 100644 docs/examples/ros_tutorials_ws/7_build_this.bash create mode 100644 docs/examples/ros_tutorials_ws/8_build_start_with.bash create mode 100644 docs/examples/ros_tutorials_ws/9_build_no_deps.bash create mode 100755 docs/examples/slowrecord create mode 100755 docs/examples/slowrun create mode 100644 docs/history.rst create mode 100644 docs/verbs/catkin_env.rst create mode 100644 docs/verbs/cli/catkin_build.txt create mode 100644 docs/verbs/cli/catkin_clean.txt create mode 100644 docs/verbs/cli/catkin_config.txt create mode 100644 docs/verbs/cli/catkin_create.txt create mode 100644 docs/verbs/cli/catkin_create_pkg.txt create mode 100644 docs/verbs/cli/catkin_env.txt create mode 100644 docs/verbs/cli/catkin_init.txt create mode 100644 docs/verbs/cli/catkin_list.txt create mode 100644 docs/verbs/cli/catkin_locate.txt create mode 100644 docs/verbs/cli/catkin_profile.txt create mode 100644 docs/verbs/cli/catkin_profile_add.txt create mode 100644 docs/verbs/cli/catkin_profile_list.txt create mode 100644 docs/verbs/cli/catkin_profile_remove.txt create mode 100644 docs/verbs/cli/catkin_profile_rename.txt create mode 100644 docs/verbs/cli/catkin_profile_set.txt create mode 100755 docs/verbs/cli/dump_cli diff --git a/docs/build_types.rst b/docs/build_types.rst index ab04a1e9..97d1759f 100644 --- a/docs/build_types.rst +++ b/docs/build_types.rst @@ -32,8 +32,6 @@ Build Stages First Subsequent Description ============== ============ ================================================== ``mkdir`` | Create package build space if it doesn't exist. ----------------------------- -------------------------------------------------- - ``buildenvgen`` | Generate environment setup file for building. ---------------------------- -------------------------------------------------- ``cmake`` ``check`` | Run CMake configure step **once** for the | first build and the ``cmake_check_build_system`` diff --git a/docs/examples/capture b/docs/examples/capture new file mode 100755 index 00000000..b04a1b77 --- /dev/null +++ b/docs/examples/capture @@ -0,0 +1,5 @@ +#!/usr/bin/env bash + +# Simple script to run another script and capture the output + +. $1 > "$1.out" diff --git a/docs/examples/failure_ws/0_init.bash b/docs/examples/failure_ws/0_init.bash new file mode 100755 index 00000000..81d518d0 --- /dev/null +++ b/docs/examples/failure_ws/0_init.bash @@ -0,0 +1,3 @@ +cp -R $(catkin locate --examples)/failure_ws /tmp/failure_ws +cd /tmp/failure_ws +catkin init diff --git a/docs/examples/failure_ws/1_build_warning.bash b/docs/examples/failure_ws/1_build_warning.bash new file mode 100644 index 00000000..b935fb12 --- /dev/null +++ b/docs/examples/failure_ws/1_build_warning.bash @@ -0,0 +1,2 @@ +cd /tmp/failure_ws # Navigate to the workspace +catkin build catkin_pkg_make_warn # Build a package with warnings diff --git a/docs/examples/failure_ws/2_build_err.bash b/docs/examples/failure_ws/2_build_err.bash new file mode 100644 index 00000000..c0802ec9 --- /dev/null +++ b/docs/examples/failure_ws/2_build_err.bash @@ -0,0 +1,2 @@ +cd /tmp/failure_ws # Navigate to the workspace +catkin build catkin_pkg_make_err # Build a package which fails diff --git a/docs/examples/failure_ws/src/catkin_pkg_cmake_err/CMakeLists.txt b/docs/examples/failure_ws/src/catkin_pkg_cmake_err/CMakeLists.txt new file mode 100644 index 00000000..94eb5677 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_cmake_err/CMakeLists.txt @@ -0,0 +1,158 @@ +cmake_minimum_required(VERSION 2.8.3) +project(catkin_pkg_cmake_err) + +## Find catkin macros and libraries +## if COMPONENTS list like find_package(catkin REQUIRED COMPONENTS xyz) +## is used, also find other catkin packages +find_package(catkin REQUIRED) + +## System dependencies are found with CMake's conventions +# find_package(Boost REQUIRED COMPONENTS system) + + +## Uncomment this if the package has a setup.py. This macro ensures +## modules and global scripts declared therein get installed +## See http://ros.org/doc/api/catkin/html/user_guide/setup_dot_py.html +# catkin_python_setup() + +################################################ +## Declare ROS messages, services and actions ## +################################################ + +## To declare and build messages, services or actions from within this +## package, follow these steps: +## * Let MSG_DEP_SET be the set of packages whose message types you use in +## your messages/services/actions (e.g. std_msgs, actionlib_msgs, ...). +## * In the file package.xml: +## * add a build_depend and a run_depend tag for each package in MSG_DEP_SET +## * If MSG_DEP_SET isn't empty the following dependencies might have been +## pulled in transitively but can be declared for certainty nonetheless: +## * add a build_depend tag for "message_generation" +## * add a run_depend tag for "message_runtime" +## * In this file (CMakeLists.txt): +## * add "message_generation" and every package in MSG_DEP_SET to +## find_package(catkin REQUIRED COMPONENTS ...) +## * add "message_runtime" and every package in MSG_DEP_SET to +## catkin_package(CATKIN_DEPENDS ...) +## * uncomment the add_*_files sections below as needed +## and list every .msg/.srv/.action file to be processed +## * uncomment the generate_messages entry below +## * add every package in MSG_DEP_SET to generate_messages(DEPENDENCIES ...) + +## Generate messages in the 'msg' folder +# add_message_files( +# FILES +# Message1.msg +# Message2.msg +# ) + +## Generate services in the 'srv' folder +# add_service_files( +# FILES +# Service1.srv +# Service2.srv +# ) + +## Generate actions in the 'action' folder +# add_action_files( +# FILES +# Action1.action +# Action2.action +# ) + +## Generate added messages and services with any dependencies listed here +# generate_messages( +# DEPENDENCIES +# std_msgs # Or other packages containing msgs +# ) + +################################### +## catkin specific configuration ## +################################### +## The catkin_package macro generates cmake config files for your package +## Declare things to be passed to dependent projects +## INCLUDE_DIRS: uncomment this if you package contains header files +## LIBRARIES: libraries you create in this project that dependent projects also need +## CATKIN_DEPENDS: catkin_packages dependent projects also need +## DEPENDS: system dependencies of this project that dependent projects also need +catkin_package( +# INCLUDE_DIRS include +# LIBRARIES catkin_pkg_cmake_err +# CATKIN_DEPENDS other_catkin_pkg +# DEPENDS system_lib +) + +########### +## Build ## +########### + +## Specify additional locations of header files +## Your package locations should be listed before other locations +# include_directories(include) + +## Declare a cpp library +# add_library(catkin_pkg_cmake_err +# src/${PROJECT_NAME}/catkin_pkg_cmake_err.cpp +# ) + +## Declare a cpp executable +# add_executable(catkin_pkg_cmake_err_node src/catkin_pkg_cmake_err_node.cpp) + +## Add cmake target dependencies of the executable/library +## as an example, message headers may need to be generated before nodes +# add_dependencies(catkin_pkg_cmake_err_node catkin_pkg_cmake_err_generate_messages_cpp) + +## Specify libraries to link a library or executable target against +# target_link_libraries(catkin_pkg_cmake_err_node +# ${catkin_LIBRARIES} +# ) + +############# +## Install ## +############# + +# all install targets should use catkin DESTINATION variables +# See http://ros.org/doc/api/catkin/html/adv_user_guide/variables.html + +## Mark executable scripts (Python etc.) for installation +## in contrast to setup.py, you can choose the destination +# install(PROGRAMS +# scripts/my_python_script +# DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION} +# ) + +## Mark executables and/or libraries for installation +# install(TARGETS catkin_pkg_cmake_err catkin_pkg_cmake_err_node +# ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION} +# LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION} +# RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION} +# ) + +## Mark cpp header files for installation +# install(DIRECTORY include/${PROJECT_NAME}/ +# DESTINATION ${CATKIN_PACKAGE_INCLUDE_DESTINATION} +# FILES_MATCHING PATTERN "*.h" +# PATTERN ".svn" EXCLUDE +# ) + +## Mark other files for installation (e.g. launch and bag files, etc.) +# install(FILES +# # myfile1 +# # myfile2 +# DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION} +# ) + +############# +## Testing ## +############# + +## Add gtest based cpp test target and link libraries +# catkin_add_gtest(${PROJECT_NAME}-test test/test_catkin_pkg_cmake_err.cpp) +# if(TARGET ${PROJECT_NAME}-test) +# target_link_libraries(${PROJECT_NAME}-test ${PROJECT_NAME}) +# endif() + +## Add folders to be run by python nosetests +# catkin_add_nosetests(test) + +add_subdirectory(sub) diff --git a/docs/examples/failure_ws/src/catkin_pkg_cmake_err/package.xml b/docs/examples/failure_ws/src/catkin_pkg_cmake_err/package.xml new file mode 100644 index 00000000..07c270d3 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_cmake_err/package.xml @@ -0,0 +1,50 @@ + + + catkin_pkg_cmake_err + 0.0.0 + The catkin_pkg_cmake_err package + + + + + jbohren + + + + + + TODO + + + + + + + + + + + + + + + + + + + + + + + + + + catkin + + + + + + + + \ No newline at end of file diff --git a/docs/examples/failure_ws/src/catkin_pkg_cmake_err/sub/CMakeLists.txt b/docs/examples/failure_ws/src/catkin_pkg_cmake_err/sub/CMakeLists.txt new file mode 100644 index 00000000..305be5b5 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_cmake_err/sub/CMakeLists.txt @@ -0,0 +1,4 @@ + +message(SEND_ERROR "This package sends an error from cmake!") +#message(SEND_ERROR "This package sends an error from cmake.\nOne\n\nTwo\n\n\nThree") + diff --git a/docs/examples/failure_ws/src/catkin_pkg_cmake_warn/CMakeLists.txt b/docs/examples/failure_ws/src/catkin_pkg_cmake_warn/CMakeLists.txt new file mode 100644 index 00000000..b9ad5754 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_cmake_warn/CMakeLists.txt @@ -0,0 +1,158 @@ +cmake_minimum_required(VERSION 2.8.3) +project(catkin_pkg_cmake_warn) + +## Find catkin macros and libraries +## if COMPONENTS list like find_package(catkin REQUIRED COMPONENTS xyz) +## is used, also find other catkin packages +find_package(catkin REQUIRED) + +## System dependencies are found with CMake's conventions +# find_package(Boost REQUIRED COMPONENTS system) + + +## Uncomment this if the package has a setup.py. This macro ensures +## modules and global scripts declared therein get installed +## See http://ros.org/doc/api/catkin/html/user_guide/setup_dot_py.html +# catkin_python_setup() + +################################################ +## Declare ROS messages, services and actions ## +################################################ + +## To declare and build messages, services or actions from within this +## package, follow these steps: +## * Let MSG_DEP_SET be the set of packages whose message types you use in +## your messages/services/actions (e.g. std_msgs, actionlib_msgs, ...). +## * In the file package.xml: +## * add a build_depend and a run_depend tag for each package in MSG_DEP_SET +## * If MSG_DEP_SET isn't empty the following dependencies might have been +## pulled in transitively but can be declared for certainty nonetheless: +## * add a build_depend tag for "message_generation" +## * add a run_depend tag for "message_runtime" +## * In this file (CMakeLists.txt): +## * add "message_generation" and every package in MSG_DEP_SET to +## find_package(catkin REQUIRED COMPONENTS ...) +## * add "message_runtime" and every package in MSG_DEP_SET to +## catkin_package(CATKIN_DEPENDS ...) +## * uncomment the add_*_files sections below as needed +## and list every .msg/.srv/.action file to be processed +## * uncomment the generate_messages entry below +## * add every package in MSG_DEP_SET to generate_messages(DEPENDENCIES ...) + +## Generate messages in the 'msg' folder +# add_message_files( +# FILES +# Message1.msg +# Message2.msg +# ) + +## Generate services in the 'srv' folder +# add_service_files( +# FILES +# Service1.srv +# Service2.srv +# ) + +## Generate actions in the 'action' folder +# add_action_files( +# FILES +# Action1.action +# Action2.action +# ) + +## Generate added messages and services with any dependencies listed here +# generate_messages( +# DEPENDENCIES +# std_msgs # Or other packages containing msgs +# ) + +################################### +## catkin specific configuration ## +################################### +## The catkin_package macro generates cmake config files for your package +## Declare things to be passed to dependent projects +## INCLUDE_DIRS: uncomment this if you package contains header files +## LIBRARIES: libraries you create in this project that dependent projects also need +## CATKIN_DEPENDS: catkin_packages dependent projects also need +## DEPENDS: system dependencies of this project that dependent projects also need +catkin_package( +# INCLUDE_DIRS include +# LIBRARIES catkin_pkg_cmake_warn +# CATKIN_DEPENDS other_catkin_pkg +# DEPENDS system_lib +) + +########### +## Build ## +########### + +## Specify additional locations of header files +## Your package locations should be listed before other locations +# include_directories(include) + +## Declare a cpp library +# add_library(catkin_pkg_cmake_warn +# src/${PROJECT_NAME}/catkin_pkg_cmake_warn.cpp +# ) + +## Declare a cpp executable +# add_executable(catkin_pkg_cmake_warn_node src/catkin_pkg_cmake_warn_node.cpp) + +## Add cmake target dependencies of the executable/library +## as an example, message headers may need to be generated before nodes +# add_dependencies(catkin_pkg_cmake_warn_node catkin_pkg_cmake_warn_generate_messages_cpp) + +## Specify libraries to link a library or executable target against +# target_link_libraries(catkin_pkg_cmake_warn_node +# ${catkin_LIBRARIES} +# ) + +############# +## Install ## +############# + +# all install targets should use catkin DESTINATION variables +# See http://ros.org/doc/api/catkin/html/adv_user_guide/variables.html + +## Mark executable scripts (Python etc.) for installation +## in contrast to setup.py, you can choose the destination +# install(PROGRAMS +# scripts/my_python_script +# DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION} +# ) + +## Mark executables and/or libraries for installation +# install(TARGETS catkin_pkg_cmake_warn catkin_pkg_cmake_warn_node +# ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION} +# LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION} +# RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION} +# ) + +## Mark cpp header files for installation +# install(DIRECTORY include/${PROJECT_NAME}/ +# DESTINATION ${CATKIN_PACKAGE_INCLUDE_DESTINATION} +# FILES_MATCHING PATTERN "*.h" +# PATTERN ".svn" EXCLUDE +# ) + +## Mark other files for installation (e.g. launch and bag files, etc.) +# install(FILES +# # myfile1 +# # myfile2 +# DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION} +# ) + +############# +## Testing ## +############# + +## Add gtest based cpp test target and link libraries +# catkin_add_gtest(${PROJECT_NAME}-test test/test_catkin_pkg_cmake_warn.cpp) +# if(TARGET ${PROJECT_NAME}-test) +# target_link_libraries(${PROJECT_NAME}-test ${PROJECT_NAME}) +# endif() + +## Add folders to be run by python nosetests +# catkin_add_nosetests(test) + +message(WARNING "This package warns you in the cmake stage") diff --git a/docs/examples/failure_ws/src/catkin_pkg_cmake_warn/package.xml b/docs/examples/failure_ws/src/catkin_pkg_cmake_warn/package.xml new file mode 100644 index 00000000..45c51571 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_cmake_warn/package.xml @@ -0,0 +1,50 @@ + + + catkin_pkg_cmake_warn + 0.0.0 + The catkin_pkg_cmake_warn package + + + + + jbohren + + + + + + TODO + + + + + + + + + + + + + + + + + + + + + + + + + + catkin + + + + + + + + \ No newline at end of file diff --git a/docs/examples/failure_ws/src/catkin_pkg_make_err/CMakeLists.txt b/docs/examples/failure_ws/src/catkin_pkg_make_err/CMakeLists.txt new file mode 100644 index 00000000..6d729032 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_make_err/CMakeLists.txt @@ -0,0 +1,156 @@ +cmake_minimum_required(VERSION 2.8.3) +project(catkin_pkg_make_err) + +## Find catkin macros and libraries +## if COMPONENTS list like find_package(catkin REQUIRED COMPONENTS xyz) +## is used, also find other catkin packages +find_package(catkin REQUIRED) + +## System dependencies are found with CMake's conventions +# find_package(Boost REQUIRED COMPONENTS system) + + +## Uncomment this if the package has a setup.py. This macro ensures +## modules and global scripts declared therein get installed +## See http://ros.org/doc/api/catkin/html/user_guide/setup_dot_py.html +# catkin_python_setup() + +################################################ +## Declare ROS messages, services and actions ## +################################################ + +## To declare and build messages, services or actions from within this +## package, follow these steps: +## * Let MSG_DEP_SET be the set of packages whose message types you use in +## your messages/services/actions (e.g. std_msgs, actionlib_msgs, ...). +## * In the file package.xml: +## * add a build_depend and a run_depend tag for each package in MSG_DEP_SET +## * If MSG_DEP_SET isn't empty the following dependencies might have been +## pulled in transitively but can be declared for certainty nonetheless: +## * add a build_depend tag for "message_generation" +## * add a run_depend tag for "message_runtime" +## * In this file (CMakeLists.txt): +## * add "message_generation" and every package in MSG_DEP_SET to +## find_package(catkin REQUIRED COMPONENTS ...) +## * add "message_runtime" and every package in MSG_DEP_SET to +## catkin_package(CATKIN_DEPENDS ...) +## * uncomment the add_*_files sections below as needed +## and list every .msg/.srv/.action file to be processed +## * uncomment the generate_messages entry below +## * add every package in MSG_DEP_SET to generate_messages(DEPENDENCIES ...) + +## Generate messages in the 'msg' folder +# add_message_files( +# FILES +# Message1.msg +# Message2.msg +# ) + +## Generate services in the 'srv' folder +# add_service_files( +# FILES +# Service1.srv +# Service2.srv +# ) + +## Generate actions in the 'action' folder +# add_action_files( +# FILES +# Action1.action +# Action2.action +# ) + +## Generate added messages and services with any dependencies listed here +# generate_messages( +# DEPENDENCIES +# std_msgs # Or other packages containing msgs +# ) + +################################### +## catkin specific configuration ## +################################### +## The catkin_package macro generates cmake config files for your package +## Declare things to be passed to dependent projects +## INCLUDE_DIRS: uncomment this if you package contains header files +## LIBRARIES: libraries you create in this project that dependent projects also need +## CATKIN_DEPENDS: catkin_packages dependent projects also need +## DEPENDS: system dependencies of this project that dependent projects also need +catkin_package( +# INCLUDE_DIRS include +# LIBRARIES catkin_pkg_make_err +# CATKIN_DEPENDS other_catkin_pkg +# DEPENDS system_lib +) + +########### +## Build ## +########### + +## Specify additional locations of header files +## Your package locations should be listed before other locations +# include_directories(include) + +## Declare a cpp library +# add_library(catkin_pkg_make_err +# src/${PROJECT_NAME}/catkin_pkg_make_err.cpp +# ) + +## Declare a cpp executable +add_executable(main main.cpp) + +## Add cmake target dependencies of the executable/library +## as an example, message headers may need to be generated before nodes +# add_dependencies(catkin_pkg_make_err_node catkin_pkg_make_err_generate_messages_cpp) + +## Specify libraries to link a library or executable target against +# target_link_libraries(catkin_pkg_make_err_node +# ${catkin_LIBRARIES} +# ) + +############# +## Install ## +############# + +# all install targets should use catkin DESTINATION variables +# See http://ros.org/doc/api/catkin/html/adv_user_guide/variables.html + +## Mark executable scripts (Python etc.) for installation +## in contrast to setup.py, you can choose the destination +# install(PROGRAMS +# scripts/my_python_script +# DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION} +# ) + +## Mark executables and/or libraries for installation +# install(TARGETS catkin_pkg_make_err catkin_pkg_make_err_node +# ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION} +# LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION} +# RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION} +# ) + +## Mark cpp header files for installation +# install(DIRECTORY include/${PROJECT_NAME}/ +# DESTINATION ${CATKIN_PACKAGE_INCLUDE_DESTINATION} +# FILES_MATCHING PATTERN "*.h" +# PATTERN ".svn" EXCLUDE +# ) + +## Mark other files for installation (e.g. launch and bag files, etc.) +# install(FILES +# # myfile1 +# # myfile2 +# DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION} +# ) + +############# +## Testing ## +############# + +## Add gtest based cpp test target and link libraries +# catkin_add_gtest(${PROJECT_NAME}-test test/test_catkin_pkg_make_err.cpp) +# if(TARGET ${PROJECT_NAME}-test) +# target_link_libraries(${PROJECT_NAME}-test ${PROJECT_NAME}) +# endif() + +## Add folders to be run by python nosetests +# catkin_add_nosetests(test) diff --git a/docs/examples/failure_ws/src/catkin_pkg_make_err/main.cpp b/docs/examples/failure_ws/src/catkin_pkg_make_err/main.cpp new file mode 100644 index 00000000..2cdb1bdd --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_make_err/main.cpp @@ -0,0 +1,4 @@ +int main(int argc, char** argv) { + int i = 0 + return i; +} diff --git a/docs/examples/failure_ws/src/catkin_pkg_make_err/package.xml b/docs/examples/failure_ws/src/catkin_pkg_make_err/package.xml new file mode 100644 index 00000000..ba2045f7 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_make_err/package.xml @@ -0,0 +1,50 @@ + + + catkin_pkg_make_err + 0.0.0 + The catkin_pkg_make_err package + + + + + jbohren + + + + + + TODO + + + + + + + + + + + + + + + + + + + + + + + + + + catkin + + + + + + + + \ No newline at end of file diff --git a/docs/examples/failure_ws/src/catkin_pkg_make_warn/CMakeLists.txt b/docs/examples/failure_ws/src/catkin_pkg_make_warn/CMakeLists.txt new file mode 100644 index 00000000..2e829cd6 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_make_warn/CMakeLists.txt @@ -0,0 +1,156 @@ +cmake_minimum_required(VERSION 2.8.3) +project(catkin_pkg_make_warn) + +## Find catkin macros and libraries +## if COMPONENTS list like find_package(catkin REQUIRED COMPONENTS xyz) +## is used, also find other catkin packages +find_package(catkin REQUIRED) + +## System dependencies are found with CMake's conventions +# find_package(Boost REQUIRED COMPONENTS system) + + +## Uncomment this if the package has a setup.py. This macro ensures +## modules and global scripts declared therein get installed +## See http://ros.org/doc/api/catkin/html/user_guide/setup_dot_py.html +# catkin_python_setup() + +################################################ +## Declare ROS messages, services and actions ## +################################################ + +## To declare and build messages, services or actions from within this +## package, follow these steps: +## * Let MSG_DEP_SET be the set of packages whose message types you use in +## your messages/services/actions (e.g. std_msgs, actionlib_msgs, ...). +## * In the file package.xml: +## * add a build_depend and a run_depend tag for each package in MSG_DEP_SET +## * If MSG_DEP_SET isn't empty the following dependencies might have been +## pulled in transitively but can be declared for certainty nonetheless: +## * add a build_depend tag for "message_generation" +## * add a run_depend tag for "message_runtime" +## * In this file (CMakeLists.txt): +## * add "message_generation" and every package in MSG_DEP_SET to +## find_package(catkin REQUIRED COMPONENTS ...) +## * add "message_runtime" and every package in MSG_DEP_SET to +## catkin_package(CATKIN_DEPENDS ...) +## * uncomment the add_*_files sections below as needed +## and list every .msg/.srv/.action file to be processed +## * uncomment the generate_messages entry below +## * add every package in MSG_DEP_SET to generate_messages(DEPENDENCIES ...) + +## Generate messages in the 'msg' folder +# add_message_files( +# FILES +# Message1.msg +# Message2.msg +# ) + +## Generate services in the 'srv' folder +# add_service_files( +# FILES +# Service1.srv +# Service2.srv +# ) + +## Generate actions in the 'action' folder +# add_action_files( +# FILES +# Action1.action +# Action2.action +# ) + +## Generate added messages and services with any dependencies listed here +# generate_messages( +# DEPENDENCIES +# std_msgs # Or other packages containing msgs +# ) + +################################### +## catkin specific configuration ## +################################### +## The catkin_package macro generates cmake config files for your package +## Declare things to be passed to dependent projects +## INCLUDE_DIRS: uncomment this if you package contains header files +## LIBRARIES: libraries you create in this project that dependent projects also need +## CATKIN_DEPENDS: catkin_packages dependent projects also need +## DEPENDS: system dependencies of this project that dependent projects also need +catkin_package( +# INCLUDE_DIRS include +# LIBRARIES catkin_pkg_make_warn +# CATKIN_DEPENDS other_catkin_pkg +# DEPENDS system_lib +) + +########### +## Build ## +########### + +## Specify additional locations of header files +## Your package locations should be listed before other locations +# include_directories(include) + +## Declare a cpp library +# add_library(catkin_pkg_make_warn +# src/${PROJECT_NAME}/catkin_pkg_make_warn.cpp +# ) + +## Declare a cpp executable +add_executable(main main.cpp) + +## Add cmake target dependencies of the executable/library +## as an example, message headers may need to be generated before nodes +# add_dependencies(catkin_pkg_make_warn_node catkin_pkg_make_warn_generate_messages_cpp) + +## Specify libraries to link a library or executable target against +# target_link_libraries(catkin_pkg_make_warn_node +# ${catkin_LIBRARIES} +# ) + +############# +## Install ## +############# + +# all install targets should use catkin DESTINATION variables +# See http://ros.org/doc/api/catkin/html/adv_user_guide/variables.html + +## Mark executable scripts (Python etc.) for installation +## in contrast to setup.py, you can choose the destination +# install(PROGRAMS +# scripts/my_python_script +# DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION} +# ) + +## Mark executables and/or libraries for installation +# install(TARGETS catkin_pkg_make_warn catkin_pkg_make_warn_node +# ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION} +# LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION} +# RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION} +# ) + +## Mark cpp header files for installation +# install(DIRECTORY include/${PROJECT_NAME}/ +# DESTINATION ${CATKIN_PACKAGE_INCLUDE_DESTINATION} +# FILES_MATCHING PATTERN "*.h" +# PATTERN ".svn" EXCLUDE +# ) + +## Mark other files for installation (e.g. launch and bag files, etc.) +# install(FILES +# # myfile1 +# # myfile2 +# DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION} +# ) + +############# +## Testing ## +############# + +## Add gtest based cpp test target and link libraries +# catkin_add_gtest(${PROJECT_NAME}-test test/test_catkin_pkg_make_warn.cpp) +# if(TARGET ${PROJECT_NAME}-test) +# target_link_libraries(${PROJECT_NAME}-test ${PROJECT_NAME}) +# endif() + +## Add folders to be run by python nosetests +# catkin_add_nosetests(test) diff --git a/docs/examples/failure_ws/src/catkin_pkg_make_warn/a.out b/docs/examples/failure_ws/src/catkin_pkg_make_warn/a.out new file mode 100755 index 0000000000000000000000000000000000000000..4a0b1ebaf98fdd3f30b8ffd5a50fcd2a5e7e7aba GIT binary patch literal 8376 zcmeHMU2Ggz6~4P`Cr%Up#7(K2w9N{(svE_VIR0VNQab)i#$lVJiGzSP9j|xS_O|O? zYj?IdRa=6bR@%BLM&iNzNbt}H5EA5}AWIb@!6m6sK|wqaXpu~mNK2Cnx6oigljS>i z?%ACgZ%TPUy!c8p=brDLzkBA+ow@gZWgxQ0@AC;Re(_mB-1&emA^R@GL8ZrZR_QV2{!!oP8dCO#{5m+|bt0l) z-Yb-3sT{m)#i{g1cXI>F#=x?OTYFlD_*pr^X7BtDvOoQIUZo8{$#>K{{1(~eYf zq`PxRD&Ce#rt?#6Q{nEm?oKV2(RRsxH^Dv0?%jVx2Euu40Y@=!!bM|1wlDm;`Joq& zJ~uYkR{Q$Gwy|Ga9qAxlzEJ(xWiuq3t4NcrU=>`L=Ga6gZRV_K)-p|jZpEk<-Dse? zYM6*7(_(LAu(!|LrR~zXV99>4K14}39X8c9GP+dL>NUnSTY0=_@{C_k~<&v~g>{K+vasMxpj+5Grl@ zr4*W}{V}QRzL33mw)Weo`pDg*M;As%N43VSCuA3m=?71(gCFv1HO~`9vDF>@xdBI| z#iI+ev(#32_Nr0HFWLfyfu;8wo9MRvbYb8_36da+QAmX@L<;fHqH(gV1C}Ev@7YcS zcrjA2LQ9dtGofXp@K^}FzZ#C*ce$r)eqFj=D&aARB1BT4oAAhA0(}MaRpN0`@jZP=_@=LfuH$GgfQm<6 zs(oRN*`QCa{hI&fz{wi_7aB;8;-I)FPS^VZY_+UrU^N4)8CcE0Y6ey_@c+#Kej8-r zD7-x5{4dM@!y8n?Y(ST_dd1JH^~?u1N*RLY{5p}!+D^&ynr7awQ?s~5-mz{}biJZ2 zir%Iu6Ix?XDK-vE%KsQF&;LR6A5P_Vn}{jppYdVE(?1Ip*2mAjEX?CKM)pTn^2n3q zeM)Xg@nO}j;Qu+{^{Us=*_*_%x3BO1VC#{QeA>$Ih$Pd|Y$n*Lb!(k%?Rg2dKi9rX z+u3=ajf$Jecd&eyE!iQ2mOD0KMMprbtWC$cmP}iT?4;1r87ran^bWRJ(J{r1rSsZI zK8XcqGA=aY#-q7$p~a7-Vb7*k)^2$!knQ!kDCQroB2%FJ~WDE{7FoT;WZQFK6a*&Q? zCMFVT%bWiHn%@Eq8cRHm!+srHWgmt2OC*RJk2~f+g$j*n)*tfg;41qRLCIBaHI=HY zwd3y8xBR-qEoG4Y`<=zB-;c&?cn8@3oL`sXa|+=2d5?$RHz|bMeq8jkUriKYrO(8hzsJ!)?=rS_n6+O)xinzhSK-;mwBe&hb-yy^W%Lz-tXH^#vFz982TwHPW@%& ze_8o|g#{Jm=g07AR7hW?%drn?OL+6;)j#Lar=1-tVU@W5r2iYpI{nkG4i!V`d;NL& z-$9nf9>>q$HQt|{CF3YOK3SjRdK+y{|GYo9*eKP?KyIN1#AF~5WgVch=~rQh-~^*?|v^?xTWXJP#>IYHD_I?I%f0ob=w zG^_mIaDonfhRGg}ea46`sfnwo#_?UiG+f+&p4aGqtD64{ccTGikps5ba@>mjND_c_ z*srgU2_RzrPC6R{h=jj?ZoH=aKkLS8@txA0kgNx2v<9l-YXyH_oJs*?MXxHqP7GJY zZz=!Jy6vnNJb%0K4T9%oH(p;p7jokbg6B~;-iUcocS5orz^u;mp0hC^HVU54+<0?& zo^s>2V%`~cLb4vft|HGX&c=Ya4d*!3a_9>Nk|nTG-3sc(uI!N}6mIA&=j;r2UoS;nGdy{~_g9j)!_Asu}UnDGL>z+wKA$#46D{PFjIC z;rV*U$qs2}<$Kfxe53zXp?l)*mGaW1>lT&vSNcr@54t36=2_qy{Vk$NJzo}ik#JFY ze`{33H-S@s7u9o@d;4hn0dVS9tH;idlsx~ZvHhPYd2b%hD0w=kqH?di3vm{BP}QB} zk5azMJQj+!V&WM48Q9-1-RwEk^YDPl9J%3o z#fw~9N-uQcsKq8HVTG2cW;C0P9y1f^xG?*_xWDJ&!9I73Jirv@-pGO8o``v1&z{2r zL*`IVZ)AYFD33B@xx6WtxU?>{4>pCFkc(6sSE=BzJm;Uf?mPfBO{Wz{re$B_xr{j; zO~+FSVGbUEuXr+T=5q-|Ux`I7z3nck=uNDZRbcYO)!g@#c_=ZK%wb!gFBQ$@5;-B$ GA^r_pfhwT@ literal 0 HcmV?d00001 diff --git a/docs/examples/failure_ws/src/catkin_pkg_make_warn/grep-errors.txt b/docs/examples/failure_ws/src/catkin_pkg_make_warn/grep-errors.txt new file mode 100644 index 00000000..1b90dde7 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_make_warn/grep-errors.txt @@ -0,0 +1,2 @@ +main.cpp: In function ‘int main(int, char**)’: +main.cpp:4:7: warning: unused variable ‘i’ [-Wunused-variable] diff --git a/docs/examples/failure_ws/src/catkin_pkg_make_warn/main b/docs/examples/failure_ws/src/catkin_pkg_make_warn/main new file mode 100755 index 0000000000000000000000000000000000000000..4a0b1ebaf98fdd3f30b8ffd5a50fcd2a5e7e7aba GIT binary patch literal 8376 zcmeHMU2Ggz6~4P`Cr%Up#7(K2w9N{(svE_VIR0VNQab)i#$lVJiGzSP9j|xS_O|O? zYj?IdRa=6bR@%BLM&iNzNbt}H5EA5}AWIb@!6m6sK|wqaXpu~mNK2Cnx6oigljS>i z?%ACgZ%TPUy!c8p=brDLzkBA+ow@gZWgxQ0@AC;Re(_mB-1&emA^R@GL8ZrZR_QV2{!!oP8dCO#{5m+|bt0l) z-Yb-3sT{m)#i{g1cXI>F#=x?OTYFlD_*pr^X7BtDvOoQIUZo8{$#>K{{1(~eYf zq`PxRD&Ce#rt?#6Q{nEm?oKV2(RRsxH^Dv0?%jVx2Euu40Y@=!!bM|1wlDm;`Joq& zJ~uYkR{Q$Gwy|Ga9qAxlzEJ(xWiuq3t4NcrU=>`L=Ga6gZRV_K)-p|jZpEk<-Dse? zYM6*7(_(LAu(!|LrR~zXV99>4K14}39X8c9GP+dL>NUnSTY0=_@{C_k~<&v~g>{K+vasMxpj+5Grl@ zr4*W}{V}QRzL33mw)Weo`pDg*M;As%N43VSCuA3m=?71(gCFv1HO~`9vDF>@xdBI| z#iI+ev(#32_Nr0HFWLfyfu;8wo9MRvbYb8_36da+QAmX@L<;fHqH(gV1C}Ev@7YcS zcrjA2LQ9dtGofXp@K^}FzZ#C*ce$r)eqFj=D&aARB1BT4oAAhA0(}MaRpN0`@jZP=_@=LfuH$GgfQm<6 zs(oRN*`QCa{hI&fz{wi_7aB;8;-I)FPS^VZY_+UrU^N4)8CcE0Y6ey_@c+#Kej8-r zD7-x5{4dM@!y8n?Y(ST_dd1JH^~?u1N*RLY{5p}!+D^&ynr7awQ?s~5-mz{}biJZ2 zir%Iu6Ix?XDK-vE%KsQF&;LR6A5P_Vn}{jppYdVE(?1Ip*2mAjEX?CKM)pTn^2n3q zeM)Xg@nO}j;Qu+{^{Us=*_*_%x3BO1VC#{QeA>$Ih$Pd|Y$n*Lb!(k%?Rg2dKi9rX z+u3=ajf$Jecd&eyE!iQ2mOD0KMMprbtWC$cmP}iT?4;1r87ran^bWRJ(J{r1rSsZI zK8XcqGA=aY#-q7$p~a7-Vb7*k)^2$!knQ!kDCQroB2%FJ~WDE{7FoT;WZQFK6a*&Q? zCMFVT%bWiHn%@Eq8cRHm!+srHWgmt2OC*RJk2~f+g$j*n)*tfg;41qRLCIBaHI=HY zwd3y8xBR-qEoG4Y`<=zB-;c&?cn8@3oL`sXa|+=2d5?$RHz|bMeq8jkUriKYrO(8hzsJ!)?=rS_n6+O)xinzhSK-;mwBe&hb-yy^W%Lz-tXH^#vFz982TwHPW@%& ze_8o|g#{Jm=g07AR7hW?%drn?OL+6;)j#Lar=1-tVU@W5r2iYpI{nkG4i!V`d;NL& z-$9nf9>>q$HQt|{CF3YOK3SjRdK+y{|GYo9*eKP?KyIN1#AF~5WgVch=~rQh-~^*?|v^?xTWXJP#>IYHD_I?I%f0ob=w zG^_mIaDonfhRGg}ea46`sfnwo#_?UiG+f+&p4aGqtD64{ccTGikps5ba@>mjND_c_ z*srgU2_RzrPC6R{h=jj?ZoH=aKkLS8@txA0kgNx2v<9l-YXyH_oJs*?MXxHqP7GJY zZz=!Jy6vnNJb%0K4T9%oH(p;p7jokbg6B~;-iUcocS5orz^u;mp0hC^HVU54+<0?& zo^s>2V%`~cLb4vft|HGX&c=Ya4d*!3a_9>Nk|nTG-3sc(uI!N}6mIA&=j;r2UoS;nGdy{~_g9j)!_Asu}UnDGL>z+wKA$#46D{PFjIC z;rV*U$qs2}<$Kfxe53zXp?l)*mGaW1>lT&vSNcr@54t36=2_qy{Vk$NJzo}ik#JFY ze`{33H-S@s7u9o@d;4hn0dVS9tH;idlsx~ZvHhPYd2b%hD0w=kqH?di3vm{BP}QB} zk5azMJQj+!V&WM48Q9-1-RwEk^YDPl9J%3o z#fw~9N-uQcsKq8HVTG2cW;C0P9y1f^xG?*_xWDJ&!9I73Jirv@-pGO8o``v1&z{2r zL*`IVZ)AYFD33B@xx6WtxU?>{4>pCFkc(6sSE=BzJm;Uf?mPfBO{Wz{re$B_xr{j; zO~+FSVGbUEuXr+T=5q-|Ux`I7z3nck=uNDZRbcYO)!g@#c_=ZK%wb!gFBQ$@5;-B$ GA^r_pfhwT@ literal 0 HcmV?d00001 diff --git a/docs/examples/failure_ws/src/catkin_pkg_make_warn/main.cpp b/docs/examples/failure_ws/src/catkin_pkg_make_warn/main.cpp new file mode 100644 index 00000000..49263360 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_make_warn/main.cpp @@ -0,0 +1,5 @@ + +int main(int argc, char** argv) { + double d = 0; + char* foo = "hello"; +} diff --git a/docs/examples/failure_ws/src/catkin_pkg_make_warn/package.xml b/docs/examples/failure_ws/src/catkin_pkg_make_warn/package.xml new file mode 100644 index 00000000..7cbe9e01 --- /dev/null +++ b/docs/examples/failure_ws/src/catkin_pkg_make_warn/package.xml @@ -0,0 +1,50 @@ + + + catkin_pkg_make_warn + 0.0.0 + The catkin_pkg_make_warn package + + + + + jbohren + + + + + + TODO + + + + + + + + + + + + + + + + + + + + + + + + + + catkin + + + + + + + + \ No newline at end of file diff --git a/docs/examples/quickstart_ws/0_quickstart.bash b/docs/examples/quickstart_ws/0_quickstart.bash new file mode 100755 index 00000000..3358123c --- /dev/null +++ b/docs/examples/quickstart_ws/0_quickstart.bash @@ -0,0 +1,13 @@ +source /opt/ros/indigo/setup.bash # Source ROS indigo to use Catkin +mkdir -p /tmp/quickstart_ws/src # Make a new workspace and source space +cd /tmp/quickstart_ws # Navigate to the workspace root +catkin init # Initialize it with a hidden marker file +cd /tmp/quickstart_ws/src # Navigate to the source space +catkin create pkg pkg_a # Populate the source space with packages... +catkin create pkg pkg_b +catkin create pkg pkg_c --catkin-deps pkg_a +catkin create pkg pkg_d --catkin-deps pkg_a pkg_b +catkin list # List the packages in the workspace +catkin build # Build all packages in the workspace +source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment +catkin clean --all # Clean all the build products diff --git a/docs/examples/quickstart_ws/1_prebuild.bash b/docs/examples/quickstart_ws/1_prebuild.bash new file mode 100755 index 00000000..8cb47d39 --- /dev/null +++ b/docs/examples/quickstart_ws/1_prebuild.bash @@ -0,0 +1,2 @@ +cd /tmp/quickstart_ws # Navigate to the workspace root +tree -aL 2 # Show prebuild directory tree diff --git a/docs/examples/quickstart_ws/1_prebuild.bash.out b/docs/examples/quickstart_ws/1_prebuild.bash.out new file mode 100644 index 00000000..ef250550 --- /dev/null +++ b/docs/examples/quickstart_ws/1_prebuild.bash.out @@ -0,0 +1,11 @@ +. +├── .catkin_tools +│   ├── default +│   └── README +└── src + ├── pkg_a + ├── pkg_b + ├── pkg_c + └── pkg_d + +7 directories, 1 file diff --git a/docs/examples/quickstart_ws/2_postbuild.bash b/docs/examples/quickstart_ws/2_postbuild.bash new file mode 100644 index 00000000..a8bd121e --- /dev/null +++ b/docs/examples/quickstart_ws/2_postbuild.bash @@ -0,0 +1,2 @@ +cd /tmp/quickstart_ws # Navigate to the workspace root +tree -aL 2 # Show postbuild directory tree diff --git a/docs/examples/quickstart_ws/2_postbuild.bash.out b/docs/examples/quickstart_ws/2_postbuild.bash.out new file mode 100644 index 00000000..f982efc2 --- /dev/null +++ b/docs/examples/quickstart_ws/2_postbuild.bash.out @@ -0,0 +1,31 @@ +. +├── build +│   ├── .built_by +│   ├── .catkin_tools.yaml +│   ├── _logs +│   ├── pkg_a +│   ├── pkg_b +│   ├── pkg_c +│   └── pkg_d +├── .catkin_tools +│   ├── default +│   └── README +├── devel +│   ├── .built_by +│   ├── .catkin +│   ├── env.sh +│   ├── etc +│   ├── lib +│   ├── .rosinstall +│   ├── setup.bash +│   ├── setup.sh +│   ├── _setup_util.py +│   ├── setup.zsh +│   └── share +└── src + ├── pkg_a + ├── pkg_b + ├── pkg_c + └── pkg_d + +17 directories, 11 files diff --git a/docs/examples/ros_tutorials_ws/0_checkout.bash b/docs/examples/ros_tutorials_ws/0_checkout.bash new file mode 100644 index 00000000..240bdee1 --- /dev/null +++ b/docs/examples/ros_tutorials_ws/0_checkout.bash @@ -0,0 +1,7 @@ +export ROS_DISTRO=indigo # Set ROS distribution +mkdir -p /tmp/ros_tutorials_ws/src # Create workspace +cd /tmp/ros_tutorials_ws/src # Navigate to source space +rosinstall_generator --deps ros_tutorials > .rosinstall # Get list of pakcages +wstool update # Checkout all packages +cd /tmp/ros_tutorials_ws # Navigate to ros workspace root +catkin init # Initialize workspace diff --git a/docs/examples/ros_tutorials_ws/1_init.bash b/docs/examples/ros_tutorials_ws/1_init.bash new file mode 100644 index 00000000..c8c8821b --- /dev/null +++ b/docs/examples/ros_tutorials_ws/1_init.bash @@ -0,0 +1,2 @@ +cd /tmp/ros_tutorials_ws # Navigate to workspace +catkin init # Initialize workspace diff --git a/docs/examples/ros_tutorials_ws/2_dry_run.bash b/docs/examples/ros_tutorials_ws/2_dry_run.bash new file mode 100644 index 00000000..4d0c055c --- /dev/null +++ b/docs/examples/ros_tutorials_ws/2_dry_run.bash @@ -0,0 +1,2 @@ +cd /tmp/ros_tutorials_ws # Navigate to workspace +catkin build --dry-run # Show the package build order diff --git a/docs/examples/ros_tutorials_ws/3_build.bash b/docs/examples/ros_tutorials_ws/3_build.bash new file mode 100644 index 00000000..e34fe8a4 --- /dev/null +++ b/docs/examples/ros_tutorials_ws/3_build.bash @@ -0,0 +1,4 @@ +cd /tmp/ros_tutorials_ws # Navigate to workspace +catkin build # Build all the packages in the workspace +ls build # Show the resulting build space +ls devel # Show the resulting devel space diff --git a/docs/examples/ros_tutorials_ws/4_build_v.bash b/docs/examples/ros_tutorials_ws/4_build_v.bash new file mode 100644 index 00000000..9b4346ba --- /dev/null +++ b/docs/examples/ros_tutorials_ws/4_build_v.bash @@ -0,0 +1,2 @@ +cd /tmp/ros_tutorials_ws # Navigate to workspace +catkin build --verbose # Build all the packages in the workspace diff --git a/docs/examples/ros_tutorials_ws/5_build_i.bash b/docs/examples/ros_tutorials_ws/5_build_i.bash new file mode 100644 index 00000000..dc286b65 --- /dev/null +++ b/docs/examples/ros_tutorials_ws/5_build_i.bash @@ -0,0 +1,2 @@ +cd /tmp/ros_tutorials_ws # Navigate to workspace +catkin build --interleave # Build all the packages in the workspace diff --git a/docs/examples/ros_tutorials_ws/6_build_partial.bash b/docs/examples/ros_tutorials_ws/6_build_partial.bash new file mode 100644 index 00000000..c820a612 --- /dev/null +++ b/docs/examples/ros_tutorials_ws/6_build_partial.bash @@ -0,0 +1,2 @@ +cd /tmp/ros_tutorials_ws # Navigate to workspace +catkin build roslib # Build roslib and its dependencies diff --git a/docs/examples/ros_tutorials_ws/7_build_this.bash b/docs/examples/ros_tutorials_ws/7_build_this.bash new file mode 100644 index 00000000..ec0dc1fa --- /dev/null +++ b/docs/examples/ros_tutorials_ws/7_build_this.bash @@ -0,0 +1,4 @@ +cd /tmp/ros_tutorials_ws # Navigate to workspace +cd src/ros/roslib # Navigate to roslib source directory +ls # Show source directory contents +catkin build --this # Build roslib and its dependencies diff --git a/docs/examples/ros_tutorials_ws/8_build_start_with.bash b/docs/examples/ros_tutorials_ws/8_build_start_with.bash new file mode 100644 index 00000000..aedcc9ca --- /dev/null +++ b/docs/examples/ros_tutorials_ws/8_build_start_with.bash @@ -0,0 +1,2 @@ +cd /tmp/ros_tutorials_ws # Navigate to workspace +catkin build --start-with roslib # Build roslib and its dependants diff --git a/docs/examples/ros_tutorials_ws/9_build_no_deps.bash b/docs/examples/ros_tutorials_ws/9_build_no_deps.bash new file mode 100644 index 00000000..345dd556 --- /dev/null +++ b/docs/examples/ros_tutorials_ws/9_build_no_deps.bash @@ -0,0 +1,2 @@ +cd /tmp/ros_tutorials_ws # Navigate to workspace +catkin build roslib --no-deps # Build roslib only diff --git a/docs/examples/slowrecord b/docs/examples/slowrecord new file mode 100755 index 00000000..3639857a --- /dev/null +++ b/docs/examples/slowrecord @@ -0,0 +1,24 @@ +#!/usr/bin/env bash + +pushd `dirname $0` > /dev/null +SCRIPTPATH=`pwd -P` +popd > /dev/null + +# Check before uploading +if [[ "$1" == "--check" ]]; then + upload="" + shift +else + upload="--yes" +fi + +# Set terminal height +if [[ "$1" == "--tall" ]]; then + height=25 + shift +else + height=15 +fi + +slowcmd="$SCRIPTPATH/slowrun $@" +urxvt -geometry 85x$height -e asciinema rec $upload --command="$slowcmd" diff --git a/docs/examples/slowrun b/docs/examples/slowrun new file mode 100755 index 00000000..7c3c154c --- /dev/null +++ b/docs/examples/slowrun @@ -0,0 +1,81 @@ +#!/usr/bin/env bash + +# This script replays a bash script, but prints the command to the console +# one character at a time as if someone was typing it. It also prints the +# name of the immediately-enclosing directory as part of simulated shell +# prompt. +# +# The script takes a single argument, the bash script to execute. It then +# prints out and executes the script, line by line. If a line contains a +# comment, the comment is also printed, but in gray. +# +# Usage: +# +# slowrun SCRIPT [START] [END] +# +# Examples: +# +# slowrun tldr.bash +# +# asciinema rec --command="./slowrun quickstart.bash " +# +# urxvt -geometry 100x30 -e asciinema rec --command="./slowrun quickstart.bash" + +function slowecho { + COLOR='' + NC='\033[0m' + printf "[\033[0;34m$(basename $(pwd) )\033[0m]$ " + sleep 1 + arg=${@} + for (( i=0; i < ${#arg}; i+=1 )) ; do + if [ "${arg:$i:1}" == "#" ]; then + COLOR='\033[1;30m' + fi + if [ "${arg:$i:1}" == " " ]; then + sleep 0.2 + else + sleep 0.05 + fi + printf "${COLOR}${arg:$i:1}" + done + printf "${NC}\n" +} + +if [[ "$1" == "--buffer" ]]; then + buffer=true + shift +else + buffer=false +fi + +lineno=0 +startno=${2:-0} +endno=${3:-1000} + +export CATKIN_TOOLS_FORCE_COLOR=1 +alias ls='ls --color' + +shopt -s expand_aliases + +while IFS='' read -r line || [[ -n "$line" ]]; do + ((lineno++)) + if (( lineno > endno )); then + break + fi + if (( lineno >= startno )); then + if [[ $line == *" #"* ]]; then + filtered_line=$(echo "$line" | perl -pe 's/^(.+?)\s*#(.*)$/\1 #\2/') + slowecho "$filtered_line" + fi + if [ "$buffer" = true ] ; then + eval $line | \ + while read -r buffered_line; do + printf "${buffered_line}\n" + sleep 0.1 + done + eval $line > /dev/null + else + eval $line + fi + fi +done < "$1" diff --git a/docs/history.rst b/docs/history.rst new file mode 100644 index 00000000..4b5eab61 --- /dev/null +++ b/docs/history.rst @@ -0,0 +1,127 @@ + +A Brief History of Catkin +========================= + +Legacy Catkin Workflow +^^^^^^^^^^^^^^^^^^^^^^ + +The core Catkin meta-buildsystem was originally designed in order to +efficiently build numerous inter-dependent, but separately developed, CMake +projects. This was developed by the Robot Operating System (ROS) +community, originally as a successor to the standard meta-buildtool +``rosbuild``. The ROS community's distributed development model with many +modular projects and the need for building distributable binary packages +motivated the design of a system which efficiently merged numerous disparate +projects so that they utilize a single target dependency tree and build space. + +To facilitate this "merged" build process, a workspace's **source space** +would contain boiler-plate "top-level" ``CMakeLists.txt`` which automatically +added all of the Catkin CMake projects below it to the single large CMake +project. + +Then the user would build this collection of projects like a single unified +CMake project with a workflow similar to the standard CMake out-of-source build +workflow. They would all be configured with one invocation of ``cmake`` and +subsequently targets would be built with one or more invocations of ``make``: + +.. code-block:: bash + + $ mkdir build + $ cd build + $ cmake ../src + $ make + +In order to help automate the merged build process, Catkin was distributed +with a command-line tool called ``catkin_make``. +This command automated the above CMake work flow while setting some +variables according to standard conventions. +These defaults would result in the execution of the following commands: + +.. code-block:: bash + + $ mkdir build + $ cd build + $ cmake ../src -DCATKIN_DEVEL_SPACE=../devel -DCMAKE_INSTALL_PREFIX=../install + $ make -j -l [optional target, e.g. install] + +An advantage of this approach is that the total configuration would be smaller +than configuring each package individually and that the Make targets can be +parallelized even amongst dependent packages. + +In practice, however, it also means that in large workspaces, modification of the +CMakeLists.txt of one package would necessitate the reconfiguration of all packages +in the entire workspace. + +A critical flaw of this approach, however, is that there is no fault isolation. +An error in a leaf package (package with no dependencies) will prevent all +packages from configuring. Packages might have colliding target names. The +merged build process can even cause CMake errors to go undetected if one package +defines variables needed by another one, and can depend on the order in which +independent packages are built. Since packages are merged into a single CMake +invocation, this approach also requires developers to specify explicit +dependencies on some targets inside of their dependencies. + +Another disadvantage of the merged build process is that it can only work on a +homogeneous workspace consisting only of Catkin CMake packages. +Other types of packages like plain CMake packages and autotools packages cannot +be integrated into a single configuration and a single build step. + +Isolated Catkin Workflow +^^^^^^^^^^^^^^^^^^^^^^^^ + +The numerous drawbacks of the merged build process and the ``catkin_make`` tool +motivated the development of the ``catkin_make_isolated`` tool. +In contrast to ``catkin_make``, the ``catkin_make_isolated`` command uses an +isolated build process, wherein each package is independently configured, +built, and loaded into the environment. + +This way, each package is built in isolation and the next packages are built on +the atomic result of the current one. This resolves the issues with target +collisions, target dependency management, and other undesirable cross-talk +between projects. +This also allows for the homogeneous automation of other buildtools like the +plain CMake or autotools. + +The isolated workflow also enabled the following features: + +- Allowing building of *part* of a workspace +- Building Catkin and non-Catkin projects into a single **devel space** +- Building packages without re-configuring or re-building their dependencies +- Removing the requirement that all packages in the workspace are free + of CMake errors before any packages can be built + +There are, however, still some problems with ``catkin_make_isolated``. First, +it is dramatically slower than ``catkin_make`` since it cannot parallelize the +building of targets or even packages which do not depend on each other. +It also lacks robustness to changes in the list of packages in the +workspace. Since it is a "released" tool, it also has strict API stability +requirements. + +Parallel Isolated Catkin Workflow and ``catkin build`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The limitations of ``catkin_make_isolated`` and the need for additional +high-level build tools lead to the development of a parallel version of +catkin make isolated, or ``pcmi``, as part of `Project +Tango `_. +``pcmi`` later became the ``build`` verb of the ``catkin`` command included +in this project. + +As such, the principle behavior of the ``build`` verb is to build each +package in isolation and in topological order while parallelizing the +building of packages which do not depend on each other. + +Other functional improvements over ``catkin_make`` and ``catkin_make_isolated`` +include the following: + +- The use of sub-command "verbs" for better organization of build options and + build-related functions +- Robustly adapting a build when packages are added to or removed from the + **source space** +- Context-aware building of a given package based on the working directory +- Utilization of persistent build metadata which catches common errors +- Support for different build "profiles" in a single workspace +- Explicit control of workspace chaining +- Additional error-checking for common environment configuration errors +- Numerous other command-line user-interface improvements + diff --git a/docs/index.rst b/docs/index.rst index 0b1e3d04..0129dc4c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,11 +9,11 @@ Catkin Command Line Tools :maxdepth: 2 Installing + History quick_start cheat_sheet Migration Guide mechanics - Workspace Configuration build_types Troubleshooting @@ -56,25 +56,22 @@ Catkin Command Line Tools development/adding_build_types Adding New Verbs -This Python package provides command line tools for working with the catkin meta-buildsystem and catkin workspaces. +This Python package provides command line tools for working with the catkin +meta-buildsystem and catkin workspaces. These tools are separate from the +Catkin CMake macros used in Catkin source packages. For documentation on +creating catkin packages, see: http://docs.ros.org/api/catkin/html/ .. note:: This package was announced in March 2015 and is still in beta. A second beta release is planned for `February 2016 `. -.. note:: - - This is the documentation for the ``catkin`` command-line tool and **not** - the Catkin CMake documentation. For documentation on creating - catkin packages, see: http://docs.ros.org/api/catkin/html/ - .. note:: Users of ``catkin_make`` and ``catkin_make_isolated`` should go to the :doc:`Migration Guide ` for help transitioning to ``catkin build``. -The ``catkin`` command +The ``catkin`` Command ^^^^^^^^^^^^^^^^^^^^^^ .. .. raw:: html @@ -95,14 +92,12 @@ such as ``git`` or ``apt-get``. Verbs include actions such as ``build`` which builds a catkin workspace or ``list`` which simply lists the catkin packages found in one or more folders. -Additionally, global options can be provided before the verb, options like -``-d`` for debug level verbosity or ``-h`` for help on the ``catkin`` CLI tool -itself. Verbs can take arbitrary arguments and options, but they must all come +Verbs can take arbitrary arguments and options, but they must all come after the verb. For more help on the usage of a particular verb, simply pass the ``-h`` or ``--help`` option after the verb. -Built-in ``catkin`` command verbs ---------------------------------- +Built-in ``catkin`` Verbs +------------------------- Each of the following verbs is built-in to the ``catkin`` command and has its own detailed documentation: @@ -110,13 +105,19 @@ Each of the following verbs is built-in to the ``catkin`` command and has its ow - :doc:`config -- Configure a catkin workspace's layout and settings ` - :doc:`clean -- Clean products generated in a catkin workspace ` - :doc:`create -- Create structures like Catkin packages ` +- :doc:`env -- Run commands with a modified environemnt ` - :doc:`init -- Initialize a catkin workspace ` - :doc:`list -- Find and list information about catkin packages in a workspace ` - :doc:`locate -- Get important workspace directory paths ` - :doc:`profile -- Manage different named configuration profiles ` -Shell support in ``catkin`` command ------------------------------------ +Contributed Third Party Verbs +----------------------------- + +- `lint -- Check catkin packages for common errors `_ + +Shell Support for the ``catkin`` Command +---------------------------------------- If you are using ``bash`` or ``zsh``, then you can source an extra setup file to gain access to some additional verbs. For more information see: :doc:`advanced/catkin_shell_verbs`. @@ -125,4 +126,5 @@ For more information see: :doc:`advanced/catkin_shell_verbs`. Extending the ``catkin`` command -------------------------------- -If you would like to add a verb to the ``catkin`` command without modifying its source, please read :doc:`development/extending_the_catkin_command`. +If you would like to add a verb to the ``catkin`` command without modifying its +source, please read :doc:`Adding New Verbs `. diff --git a/docs/mechanics.rst b/docs/mechanics.rst index 8943b488..27961938 100644 --- a/docs/mechanics.rst +++ b/docs/mechanics.rst @@ -1,84 +1,86 @@ Workspace Mechanics =================== -This chapter defines how Catkin workspaces are organized and used, as well as -some standardized nomenclature for describing elements of a Catkin workspace. -Unlike integrated development environments (IDEs) which normally only manage -single projects, the purpose of Catkin is to enable the simultaneous -compilation of numerous independently-authored projects. As such, these -projects need to be organized in a "workspace" which contains both the source -and build products for a collection of "packages." +This chapter defines the organization, composition, and use of Catkin +workspaces. Catkin workspaces enable rapid simulatnous building and +executing of numerous interdependent projects. These projects do not need to +share the sme buildtool, but they do need to be able to either build or install +to a FHS tree. +Unlike integrated development +environments (IDEs) which normally only manage single projects, the purpose of +Catkin is to enable the simultaneous compilation of numerous +independently-authored projects. Anatomy of a Catkin Workspace ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A standard catkin workspace, as defined by `REP-0128 -`_, is a folder with a prescribed set -"spaces", each of which is normally a folder within the workspace: - -- **source space** -- default: ``./src`` -- **build space** -- default: ``./build`` -- **devel space** -- default: ``./devel`` -- **install space** -- default: ``./install`` - -Though there are standard conventions for the layout and names of the -workspace's various spaces, they can be renamed for a given build -using the ``catkin config`` verb. +`_, is a directory with a prescribed set +of "spaces", each of which is contained within a directory under the workspace +root. The spaces that comprise the workspace are described in the following +sections. + +=============== =============== ====================================================== + Space Default Path Contents +=============== =============== ====================================================== + Source Space ``./src`` All source packages. + Build Space ``./build`` Intermediate build products for each package. + Devel Space ``./devel`` FHS tree containing all final build products. + Install Space ``./install`` FHS tree containing products of ``install`` targets. +=============== =============== ====================================================== + +In addition to these user-facing directories, ``catkin_tools`` also creates a +hidden ``.catkin_tools`` directory, which stores persistent build +configuration. source space ------------ -The **source space** is where the code for your packages resides and normally -is in the folder ``/path/to/workspace/src``. The build command considers -**source space** to be read-only, in that during a build no files or folders -should be created or modified in that folder. Therefore catkin workspaces -are said to be built "out of source", which simply means that the folder in -which you build your code is not under or part of the folder with contains -the source code. +The **source space** contains all of the source packages to be built in the +workspace, as such, it is the only directory required to build a workspace. The +**source space** is also the only directory in the catkin workspace which is not +modified by any ``catkin`` command verb. No build products are written to the +source space, they are all built "out-of-source" in the **build space**, +described in the next section. build space ----------- -Temporary build files are put into the **build space**, which by default is in -the ``/path/to/workspace/build`` folder. The **build space** is the working -directory in which commands like ``cmake`` and ``make`` are run. +Intermediate build products are written in the **build space**. The **build +space** contains an isolated build directory for each package, as well as +the log files which capture the output from each build stage. It is from these +directories where commands like ``cmake`` and ``make`` are run. devel space ----------- -Generated files, like executables, libraries, pkg-config files, CMake config -files, or message code, are placed in the **devel space**. -By convention the **devel space** is located as a peer to the **source -space** and **build space** in the ``/path/to/workspace/devel`` folder. -The layout of the **devel space** is intended to mimic the root of an `FHS -filesystem `_, -with folders like ``include``, ``lib``, ``bin``, and ``share``. Running code is -possible from **devel space** because references to the **source space** are -created. +Build products like executables, libraries, pkg-config files, and CMake config +files, are generated in the **devel space**. The **devel space** is organized +as an `FHS `_ +tree. + +Some buildtools simply treat the **devel space** as an install prefix, but other +buildtools like ``catkin``, itself, can build targets directly into the **devel +space** in order to skip the additional install step. For such packages, executing +programs from the develspace sometimes requires that the source space is still +available. + +At the root of the **devel space** is a set of environment setup files which can +be "sourced" in order to properly execute the space's products. install space ------------- -Finally, if the packages in the workspace are setup for installing, the -``--install`` option can be invoked to install the packages to the -``CMAKE_INSTALL_PREFIX``, which in `REP-0128 -`_ terms is the **install space**. -The **install space**, like the **devel space**, has an FHS layout along with -some generated setup files. -The **install space** is set to ``/path/to/workspace/install`` by changing -the ``CMAKE_INSTALL_PREFIX`` by default. -This is done to prevent users from accidentally trying to install to the -normal ``CMAKE_INSTALL_PREFIX`` path, ``/usr/local``. -Unlike the **devel space**, the **install space** is completely standalone -and does not require the **source space** or **build space** to function, and -is suitable for packaging. - -Additional Workspace Directories with ``catkin_tools`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Hidden Marker / Config Directory --------------------------------- +Finally, if the workspace is configured to install packages, the each will be +installed into the **install space**. The **install space** has an FHS layout +like the **devel space**, except it is entirely self-contained. + +Additional Files Generated by ``catkin_tools`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configuration Directory +----------------------- In addition to the standard workspace structure, ``catkin_tools`` also adds a marker directory called ``.catkin_tools`` at the root of the workspace. This @@ -93,19 +95,35 @@ the active configuration profile if it is different than ``default``. Build Log Directory ------------------- -Another addition is the ``build_logs`` directory which is generated in the -**build space** and contains individual build logs for each package. +The ``catkin`` command also generates a log directory called ``_logs`` in the +**build space** and contains individual build logs for each package. Logs for +each package are written in subdirectories with the same name as the package. + +The latest log for each verb and stage in a given package's log directory is +also written with the format: + +.. code-block:: bash + + {VERB}.{STAGE}.log + +Each previous logfile has the following format, where ``{INDEX}`` begins at +``000`` and increases with each execution of that verb and stage: + +.. code-block:: bash + + {VERB}.{STAGE}.{INDEX}.log Environment Setup Files ^^^^^^^^^^^^^^^^^^^^^^^ -In addition to the FHS folders, some setup scripts are generated in the **devel -space**, e.g. ``setup.bash`` or ``setup.zsh``. -These setup scripts are intended to make it easier to use the resulting **devel -space** for building on top of the packages that were just built or for running -programs built by those packages. -The setup script can be used like this in ``bash``: +The FHS trees of the **devel space** and **install space** also contain several +environemnt "setup" scripts. These setup scripts are intended to make it easier +to use the resulting FHS tree for building other source code or for running +programs built by the packages in the workspace. + +The setup script can be used +like this in ``bash``: .. code-block:: bash @@ -117,14 +135,44 @@ Or like this in ``zsh``: % source /path/to/workspace/devel/setup.zsh -Sourcing these setup scripts adds this workspace and any "underlaid" -workspaces to your environment, prefixing the ``CMAKE_PREFIX_PATH``, -``PKG_CONFIG_PATH``, ``PATH``, ``LD_LIBRARY_PATH``, ``CPATH``, and -``PYTHONPATH`` with local workspace folders. - -The setup scripts will also execute any shell hooks exported by packages in the -workspace, which is how ``roslib``, for example, sets the ``ROS_PACKAGE_PATH`` -environment variable. +Sourcing these setup scripts adds this workspace and any "underlaid" workspaces +to your environment, prefixing several environment variables with the +appropriate local workspace folders. + +============================= ================================================== + Environment Variable | Description +============================= ================================================== + CMAKE_PREFIX_PATH_ | Used by CMake to find development packages, \ + | and used by Catkin for workspace chaining. +----------------------------- -------------------------------------------------- + CPATH_ | Used by GCC to search for development headers. +----------------------------- -------------------------------------------------- + LD_LIBRARY_PATH_ [1]_ | Search path for dynamically loadable libraries. +----------------------------- -------------------------------------------------- + DYLD_LIBRARY_PATH_ [2]_ | Search path for dynamically loadable libraries. +----------------------------- -------------------------------------------------- + PATH_ | Search path for executables. +----------------------------- -------------------------------------------------- + PKG_CONFIG_PATH_ | Search path for ``pkg-config`` files. +----------------------------- -------------------------------------------------- + PYTHONPATH_ | Search path for Python modules. +============================= ================================================== + +.. _CMAKE_PREFIX_PATH: https://cmake.org/cmake/help/v3.0/variable/CMAKE_PREFIX_PATH.html +.. _CPATH: https://gcc.gnu.org/onlinedocs/cpp/Environment-Variables.html +.. _LD_LIBRARY_PATH: http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN80 +.. _DYLD_LIBRARY_PATH: https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/dyld.1.html +.. _PATH: https://en.wikipedia.org/wiki/PATH_(variable) +.. _PKG_CONFIG_PATH: http://linux.die.net/man/1/pkg-config +.. _PYTHONPATH: https://docs.python.org/2/using/cmdline.html#envvar-PYTHONPATH + +.. [1] GNU/Linux Only +.. [2] Mac OS X Only +.. [3] Windows Only + +The setup scripts will also execute any Catkin "env-hooks" exported by packages +in the workspace. For example, this is how ``roslib`` sets the +``ROS_PACKAGE_PATH`` environment variable. .. note:: @@ -137,158 +185,152 @@ environment variable. loose the functionality provided by them, namely extending the environment and executing environment hooks. -Workspace Packages and Dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Source Packages and Dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A package is any folder which contains a ``package.xml`` as defined by the ROS +community in ROS Enhancement Proposals +`REP-0127 `_ +and +`REP-0140 `_. + +The ``catkin build`` command builds packages in the topological order +determined by the dependencies listed in the package's ``package.xml`` file. +For more information on which dependencies contribute to the build order, see +the :doc:`build verb documentation`. + +Additionally, the ``build_type`` tag is used to determine which build stages to +use on the package. Supported build types are listed in :doc:`Build Types +`. Packages without a ``build_type`` tag are assumed to be catkin +packages. + +For example, plain CMake packages can be built by adding a ``package.xml`` file +to the root of their source tree with the ``build_type`` flag set to ``cmake`` +and appropriate ``build_depend`` and ``run_depend`` tags set, as described in +`REP-0136 `_. This can been done to +build packages like ``opencv``, ``pcl``, and ``flann``. + +Workspace Configuration +^^^^^^^^^^^^^^^^^^^^^^^ + +Most ``catkin`` commands which modify a workspace's configuration will +display the standard configuration summary, as shown below: + +.. code-block:: bash + + $ cd /tmp/path/to/my_catkin_ws + $ catkin config + -------------------------------------------------------------- + Profile: default + Extending: None + Workspace: /tmp/path/to/my_catkin_ws + Source Space: [exists] /tmp/path/to/my_catkin_ws/src + Build Space: [missing] /tmp/path/to/my_catkin_ws/build + Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel + Install Space: [missing] /tmp/path/to/my_catkin_ws/install + DESTDIR: None + -------------------------------------------------------------- + Devel Space Layout: merged + Install Packages: False + Isolate Installs: False + -------------------------------------------------------------- + Additional CMake Args: None + Additional Make Args: None + Additional catkin Make Args: None + Internal Make Job Server: True + Cache Job Environments: False + -------------------------------------------------------------- + Whitelisted Packages: None + Blacklisted Packages: None + -------------------------------------------------------------- + Workspace configuration appears valid. + -------------------------------------------------------------- + +This summary describes the layout of the workspace as well as other important +settings which influence build and execution behavior. Each of these options +can be modified either with the ``config`` verb's options described in the full +command-line usage or by changing environment variables. The summary is +composed of the following sections: + +Overview Section +---------------- + +- **Profile** -- The name of this configuration. +- **Extending** -- Describes if your current configuration will extend another Catkin workspace, and through which mechanism it determined the location of the extended workspace: + + - *No Chaining* + + .. code-block:: bash + + Extending: None + + - *Implicit Chaining* -- Derived from the ``CMAKE_PREFIX_PATH`` environment or cache variable. + + .. code-block:: bash -A workspace's packages consist of any packages found in the **source space**. -A package is any folder which contains a ``package.xml`` as defined in -`REP-0127 `_. + Extending: [env] /opt/ros/hydro -The ``catkin build`` command determines the order in which packages are built -based on the ``depend``, ``build_depend``, ``run_depend``, and ``build_type`` -tags in a package's ``package.xml`` file. + .. code-block:: bash +. + Extending: [cached] /opt/ros/hydro -- The ``*_depend`` tags are used to determine the topological build order of - the packages. -- The ``build_type`` tag is used to determine which build work flow to use on - the package. + - *Explicit Chaining* -- Specified by ``catkin config --extend`` -Packages without an explicitly defined ``build_type`` tag are assumed to be -catkin packages, but plain CMake packages can be built by adding a -``package.xml`` file to the root of their source tree with the ``build_type`` -flag set to ``cmake`` and appropriate ``build_depend`` and ``run_depend`` tags -set, as described in `REP-0136 `_. -This has been done in the past for building packages like ``opencv``, ``pcl``, -and ``flann``. + .. code-block:: bash -Understanding the Build Process -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Extending: [explicit] /opt/ros/hydro -Legacy Catkin Workflow +- **[* Space]** -- Lists the paths to each of the catkin "spaces" and whether or not they exist +- **DESTDIR** -- An optional prefix to the **install space** as defined by `GNU Standards `_ + +Build Product Layout Section +---------------------------- + +- **Devel Space Layout** -- The organization of the **devel space**. + + - *Merged* -- Write products from all packages to a single FHS tree. This is most similar to the behavior of ``catkin_make``. + - *Isolated* -- Write products from each package into independent isolated FHS trees. this is most similar to the behavior of ``catkin_make_isolated``. + - *Linked* -- Write products from each package into independent isolated FHS trees, and symbolically link them into a merged FHS tree. + +- **Install Packages** -- Enable creating and installation into the **install space** +- **Isolate Installs** -- Installs products into individual FHS subdirectories in the **install space** + +Build Tool Arguments Section +---------------------------- + +- **Additional CMake Args** -- Arguments to be passed to CMake during the *configuration* step for all packages to be built. +- **Additional Make Args** -- Arguments to be passed to Make during the *build* step for all packages to be built. +- **Additional catkin Make Args** -- Similar to **Additional Make Args** but only applies to Catkin packages. +- **Internal Make Job Server** -- Whether or not the internal job server should be used to coordinate parallel build jobs. +- **Cache Job Environments** -- Whether or not environment variables should be cached between build jobs. + +Package Filter Section ---------------------- -The core Catkin meta-buildsystem was originally designed in order to -efficiently build numerous inter-dependent, but separately developed, CMake -projects. This was developed by the Robot Operating System (ROS) -community, originally as a successor to the standard meta-buildtool -``rosbuild``. The ROS community's distributed development model with many -modular projects and the need for building distributable binary packages -motivated the design of a system which efficiently merged numerous disparate -projects so that they utilize a single target dependency tree and build space. - -To facilitate this "merged" build process, a workspace's **source space** -would contain boiler-plate "top-level" ``CMakeLists.txt`` which automatically -added all of the Catkin CMake projects below it to the single large CMake -project. - -Then the user would build this collection of projects like a single unified -CMake project with a workflow similar to the standard CMake out-of-source build -workflow. They would all be configured with one invocation of ``cmake`` and -subsequently targets would be built with one or more invocations of ``make``: +- **Package Whitelist** -- Packages that will be built with a bare call to ``catkin build``. +- **Package Blacklist** -- Packages that will *not* be built unless explicitly named. -.. code-block:: bash +Notes Section +------------- - $ mkdir build - $ cd build - $ cmake ../src - $ make +The summary will sometimes contain notes about the workspace or the action that +you're performing, or simply tell you that the workspace configuration appears +valid. -In order to help automate the merged build process, Catkin was distributed -with a command-line tool called ``catkin_make``. -This command automated the above CMake work flow while setting some -variables according to standard conventions. -These defaults would result in the execution of the following commands: +Warnings Section +---------------- -.. code-block:: bash +If something is wrong with your configuration such as a missing source space, +an additional section will appear at the bottom of the summary with details on +what is wrong and how you can fix it. + +Workspace Chaining / Extending +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - $ mkdir build - $ cd build - $ cmake ../src -DCATKIN_DEVEL_SPACE=../devel -DCMAKE_INSTALL_PREFIX=../install - $ make -j -l [optional target, e.g. install] - -An advantage of this approach is that the total configuration would be smaller -than configuring each package individually and that the Make targets can be -parallelized even amongst dependent packages. - -In practice, however, it also means that in large workspaces, modification of the -CMakeLists.txt of one package would necessitate the reconfiguration of all packages -in the entire workspace. - -A critical flaw of this approach, however, is that there is no fault isolation. -An error in a leaf package (package with no dependencies) will prevent all -packages from configuring. Packages might have colliding target names. The -merged build process can even cause CMake errors to go undetected if one package -defines variables needed by another one, and can depend on the order in which -independent packages are built. Since packages are merged into a single CMake -invocation, this approach also requires developers to specify explicit -dependencies on some targets inside of their dependencies. - -Another disadvantage of the merged build process is that it can only work on a -homogeneous workspace consisting only of Catkin CMake packages. -Other types of packages like plain CMake packages and autotools packages cannot -be integrated into a single configuration and a single build step. - -Isolated Catkin Workflow ------------------------- - -The numerous drawbacks of the merged build process and the ``catkin_make`` tool -motivated the development of the ``catkin_make_isolated`` tool. -In contrast to ``catkin_make``, the ``catkin_make_isolated`` command uses an -isolated build process, wherein each package is independently configured, -built, and loaded into the environment. - -This way, each package is built in isolation and the next packages are built on -the atomic result of the current one. This resolves the issues with target -collisions, target dependency management, and other undesirable cross-talk -between projects. -This also allows for the homogeneous automation of other buildtools like the -plain CMake or autotools. - -The isolated workflow also enabled the following features: - -- Allowing building of *part* of a workspace -- Building Catkin and non-Catkin projects into a single **devel space** -- Building packages without re-configuring or re-building their dependencies -- Removing the requirement that all packages in the workspace are free - of CMake errors before any packages can be built - -There are, however, still some problems with ``catkin_make_isolated``. First, -it is dramatically slower than ``catkin_make`` since it cannot parallelize the -building of targets or even packages which do not depend on each other. -It also lacks robustness to changes in the list of packages in the -workspace. Since it is a "released" tool, it also has strict API stability -requirements. - -Parallel Isolated Catkin Workflow and ``catkin build`` ------------------------------------------------------- - -The limitations of ``catkin_make_isolated`` and the need for additional -high-level build tools lead to the development of a parallel version of -catkin make isolated, or ``pcmi``, as part of `Project -Tango `_. -``pcmi`` later became the ``build`` verb of the ``catkin`` command included -in this project. - -As such, the principle behavior of the ``build`` verb is to build each -package in isolation and in topological order while parallelizing the -building of packages which do not depend on each other. - -Other functional improvements over ``catkin_make`` and ``catkin_make_isolated`` -include the following: - -- The use of sub-command "verbs" for better organization of build options and - build-related functions -- Robustly adapting a build when packages are added to or removed from the - **source space** -- Context-aware building of a given package based on the working directory -- Utilization of persistent build metadata which catches common errors -- Support for different build "profiles" in a single workspace -- Explicit control of workspace chaining -- Additional error-checking for common environment configuration errors -- Numerous other command-line user-interface improvements - -Workspace Chaining and the Importance of CMAKE_PREFIX_PATH -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +An important property listed in the configuration configuration which deserves +attention is the summary value of the ``Extending`` property. This affects +which other collections of libraries and packages which will be visible to your +workspace. This is process called "workspace chaining." Above, it's mentioned that the Catkin setup files export numerous environment variables, including ``CMAKE_PREFIX_PATH``. Since CMake 2.6.0, the @@ -337,4 +379,63 @@ command adds an explicit extension interface to override the value of build in one workspace will not cause products in any other workspace to be built. +The information about which workspace to extend can come from a few different +sources, and can be classified in one of three ways: + +No Chaining +----------- + +This is what is shown in the above example configuration and it implies that +there are no other Catkin workspaces which this workspace extends. The user has +neither explicitly specified a workspace to extend, and the +``CMAKE_PREFIX_PATH`` environment variable is empty: + +.. code-block:: bash + + Extending: None + +Implicit Chaining via ``CMAKE_PREFIX_PATH`` Environment or Cache Variable +------------------------------------------------------------------------- + +In this case, the ``catkin`` command is *implicitly* assuming that you want +to build this workspace against resources which have been built into the +directories listed in your ``CMAKE_PREFIX_PATH`` environment variable. As +such, you can control this value simply by changing this environment +variable. + +For example, ROS users who load their system's installed ROS environment by +calling something similar to ``source /opt/ros/hydro/setup.bash`` will +normally see an ``Extending`` value such as: + +.. code-block:: bash + + Extending: [env] /opt/ros/hydro + +If you don't want to extend the given workspace, unsetting the +``CMAKE_PREFIX_PATH`` environment variable will change it back to none. You can +also alternatively + +Once you have built your workspace once, this ``CMAKE_PREFIX_PATH`` will be +cached by the underlying CMake buildsystem. As such, the ``Extending`` status +will subsequently describe this as the "cached" extension path: + +.. code-block:: bash + + Extending: [cached] /opt/ros/hydro + +Once the extension mode is cached like this, you must use ``catkin clean`` to +before changing it to something else. + +Explicit Chaining via ``catkin config --extend`` +------------------------------------------------ + +This behaves like the above implicit chaining except it means that this +workspace is *explicitly* extending another workspace and the workspaces +which the other workspace extends, recursively. This can be set with the +``catkin config --extend`` command. It will override the value of +``CMAKE_PREFIX_PATH`` and persist between builds. + +.. code-block:: bash + + Extending: [explicit] /tmp/path/to/other_ws diff --git a/docs/migration.rst b/docs/migration.rst index 8245a963..1fb132e4 100644 --- a/docs/migration.rst +++ b/docs/migration.rst @@ -32,6 +32,13 @@ Operational Differences built before the current package. - ``catkin_tools`` and ``catkin_make`` can use the same source space, but they must use different build, devel, and install spaces. +- ``catkin build`` generates ``.catkin`` files and subsequently + ``ROS_PACKAGE_PATH`` variables where each source package is listed, individually, + instead of just listing the source space for the workspace. +- ``catkin build`` passes CMake command line arguments to multiple packages. + Since not all packages accept the same CMake arguments, the ``cmake`` command + is invoked with ``--no-warn-unused-cli``. This means there will be no warnings + for unused variables passed to ``cmake``. IDE Integration ^^^^^^^^^^^^^^^ diff --git a/docs/quick_start.rst b/docs/quick_start.rst index e14b8a41..c5cc892f 100644 --- a/docs/quick_start.rst +++ b/docs/quick_start.rst @@ -13,23 +13,12 @@ TL;DR The following is an example workflow and sequence of commands using default settings: -.. code-block:: bash - - $ mkdir -p /tmp/path/to/my_catkin_ws/src # Make a new workspace and source space - $ cd /tmp/path/to/my_catkin_ws # Navigate to the workspace root - $ catkin init # Initialize it with a hidden marker file - $ cd /tmp/path/to/my_catkin_ws/src # Navigate to the source space - $ catkin create pkg pkg_a # Populate the source space with packages... - $ catkin create pkg pkg_b - $ catkin create pkg pkg_c --catkin-deps pkg_a - $ catkin create pkg pkg_d --catkin-deps pkg_a pkg_b - $ catkin build # Build all packages in the workspace - $ source ../devel/setup.bash # Load the workspace's environment - $ catkin clean --all # Clean the build products - $ catkin build pkg_d # Build `pkg_d` and its deps - $ cd /tmp/path/to/my_catkin_ws/src/pkg_c # Navigate to `pkg_c`'s source directory - $ catkin build --this # Build `pkg_c` and its deps - $ catkin build --this --no-deps # Rebuild only `pkg_c` +.. literalinclude:: examples/quickstart_ws/0_quickstart.bash + :language: bash + +.. raw:: html + +

Initializing a New Workspace ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -39,33 +28,11 @@ build``, it's good practice to initialize a catkin workspace explicitly. This is done by simply creating a new workspace with an empty **source space** (named ``src`` by default) and calling ``catkin init`` from the workspace root: -.. code-block:: bash - - $ mkdir -p /tmp/path/to/my_catkin_ws/src - $ cd /tmp/path/to/my_catkin_ws - $ catkin init - -------------------------------------------------------------- - Profile: default - Extending: None - Workspace: /tmp/path/to/my_catkin_ws - Source Space: [exists] /tmp/path/to/my_catkin_ws/src - Build Space: [missing] /tmp/path/to/my_catkin_ws/build - Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel - Install Space: [missing] /tmp/path/to/my_catkin_ws/install - DESTDIR: None - -------------------------------------------------------------- - Isolate Develspaces: False - Install Packages: False - Isolate Installs: False - -------------------------------------------------------------- - Additional CMake Args: None - Additional Make Args: None - Additional catkin Make Args: None - -------------------------------------------------------------- - Workspace configuration appears valid. - -------------------------------------------------------------- - -Now the directory ``/tmp/path/to/my_catkin_ws`` has been initialized and ``catkin +.. literalinclude:: examples/quickstart_ws/0_quickstart.bash + :language: bash + :lines: 1-4 + +Now the directory ``/tmp/quickstart-init`` has been initialized and ``catkin init`` has printed the standard configuration summary to the console with the default values. This summary describes the layout of the workspace as well as other important settings which influence build and execution behavior. @@ -106,39 +73,21 @@ or more empty ones. As shown above, the default path for a Catkin **source space** is `./src` relative to the workspace root. A standard Catkin package is simply a directory with a ``CMakeLists.txt`` file and a ``package.xml`` file. For more information on Catkin packages see :doc:`workspace mechanics -`. The shell interaction below shows the creation of three -trivial packages: ``pkg_a``, ``pkg_b``, and ``another_one``: - -.. code-block:: bash - - $ cd /tmp/path/to/my_catkin_ws/src - $ catkin_create_pkg pkg_a - Created file pkg_a/CMakeLists.txt - Created file pkg_a/package.xml - Successfully created files in /tmp/path/to/my_catkin_ws/src/pkg_a. Please adjust the values in package.xml. - $ catkin_create_pkg pkg_b - Created file pkg_b/CMakeLists.txt - Created file pkg_b/package.xml - Successfully created files in /tmp/path/to/my_catkin_ws/src/pkg_b. Please adjust the values in package.xml. - $ catkin_create_pkg another_one - Created file another_one/CMakeLists.txt - Created file another_one/package.xml - Successfully created files in /tmp/path/to/my_catkin_ws/src/another_one. Please adjust the values in package.xml. +`. The shell interaction below shows the creation of four +empty packages: ``pkg_a``, ``pkg_b``, ``pkg_c``, and ``pkg_d``: + +.. literalinclude:: examples/quickstart_ws/0_quickstart.bash + :language: bash + :lines: 5-10 After these operations, your workspace's local directory structure would look like the followng (to two levels deep): -.. code-block:: bash +.. literalinclude:: examples/quickstart_ws/1_prebuild.bash + :language: bash - $ cd /tmp/path/to/my_catkin_ws - $ tree -aL 2 - . - ├── .catkin_tools - │   └── README - └── src - ├── another_one - ├── pkg_a - └── pkg_b +.. literalinclude:: examples/quickstart_ws/1_prebuild.bash.out + :language: text Now that there are some packages in the workspace, Catkin has something to build. @@ -160,52 +109,20 @@ then ``catkin build`` would need to be called from the workspace root. Based on the default configuration, it will locate the packages in the **source space** and build each of them. -.. code-block:: bash - - $ catkin build - -------------------------------------------------------------- - Profile: default - Extending: None - Workspace: /tmp/path/to/my_catkin_ws - Source Space: [exists] /tmp/path/to/my_catkin_ws/src - Build Space: [missing] /tmp/path/to/my_catkin_ws/build - Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel - Install Space: [missing] /tmp/path/to/my_catkin_ws/install - DESTDIR: None - -------------------------------------------------------------- - Isolate Develspaces: False - Install Packages: False - Isolate Installs: False - -------------------------------------------------------------- - Additional CMake Args: None - Additional Make Args: None - Additional catkin Make Args: None - -------------------------------------------------------------- - Workspace configuration appears valid. - -------------------------------------------------------------- - Found '3' packages in 0.0 seconds. - Starting ==> another_one - Starting ==> pkg_a - Starting ==> pkg_b - Finished <== pkg_b [ 2.0 seconds ] - Finished <== another_one [ 2.0 seconds ] - Finished <== pkg_a [ 3.4 seconds ] - [build] Finished. - [build] Runtime: 3.4 seconds +.. literalinclude:: examples/quickstart_ws/0_quickstart.bash + :language: bash + :lines: 11 + Calling ``catkin build`` will generate ``build`` and ``devel`` directories (as described in the config summary above) and result in a directory structure like the following (to one level deep): -.. code-block:: bash +.. literalinclude:: examples/quickstart_ws/2_postbuild.bash + :language: bash - $ cd /tmp/path/to/my_catkin_ws - $ tree -aL 1 - . - ├── build - ├── .catkin_tools - ├── devel - └── src +.. literalinclude:: examples/quickstart_ws/2_postbuild.bash.out + :language: text Intermediate build products (CMake cache files, Makefiles, object files, etc.) are generated in the ``build`` directory, or **build space** and final build @@ -227,9 +144,9 @@ workspace. Both the **devel space** or the **install space** are valid **result spaces**. In the default build configuration, only the **devel space** is generated. You can load the environment for your respective shell like so: -.. code-block:: bash - - $ source /tmp/path/to/my_catkin_ws/devel/setup.bash +.. literalinclude:: examples/quickstart_ws/0_quickstart.bash + :language: bash + :lines: 12 At this point you should be able to use products built by any of the packages in your workspace. @@ -259,14 +176,13 @@ command. Just like the other verbs, ``catkin clean`` is context-aware, so it only needs to be called from a directory under the workspace root. In order to clean the **build space** and **devel space** for the workspace, -you can use any following command: +you can use the following command: -.. code-block:: bash - - $ catkin clean --build --devel - Removing buildspace: /tmp/path/to/my_catkin_ws/build - Removing develspace: /tmp/path/to/my_catkin_ws/devel +.. literalinclude:: examples/quickstart_ws/0_quickstart.bash + :language: bash + :lines: 13 For more information on less aggressive cleaning options see the :doc:`clean verb ` documentation. + diff --git a/docs/verbs/catkin_build.rst b/docs/verbs/catkin_build.rst index c12f1bb0..ed28c8a9 100644 --- a/docs/verbs/catkin_build.rst +++ b/docs/verbs/catkin_build.rst @@ -2,27 +2,21 @@ ================================== The ``build`` verb is used to build one or more packages in a catkin workspace. -Like most verbs, ``build`` is context-aware. This means that it can be executed from within any directory contained by an *initialized* workspace. - -If a workspace is not yet initialized, ``build`` can initialize it, but only if it is called from the workspace root and the default workspace structure is desired. - -Workspaces can also be built from arbitrary working directories if the user specifies the path to the workspace with the ``--workspace`` option. +Like most verbs, ``build`` is context-aware and can be executed from within any +directory contained by an initialized workspace. If a workspace is not yet +initialized, ``build`` can initialize it with the default configuration, but +only if it is called from the workspace root. Specific workspaces can also be +built from arbitrary working directories with the ``--workspace`` option. .. note:: - To set up the workspace and clone the repositories used in the following - examples, you can use `rosinstall_generator `_ and `wstool `_. This - clones all of the ROS packages necessary for building the introductory - ROS tutorials: - - .. code-block:: bash + To set up a workspace and clone the repositories used in the following + examples, you can use `rosinstall_generator `_ and `wstool `_. + The following clones all of the ROS packages necessary for building the + introductory ROS tutorials: - $ mkdir -p /tmp/path/to/my_catkin_ws/src - $ cd /tmp/path/to/my_catkin_ws - $ catkin init - $ cd /tmp/path/to/my_catkin_ws/src - $ rosinstall_generator --deps ros_tutorials > .rosinstall - $ wstool update + .. literalinclude:: ../examples/ros_tutorials_ws/0_checkout.bash + :language: bash Basic Usage ^^^^^^^^^^^ @@ -34,80 +28,15 @@ Before actually building anything in the workspace, it is useful to preview which packages will be built and in what order. This can be done with the ``--dry-run`` option: -.. code-block:: bash - - $ catkin build --dry-run - -------------------------------------------------------------- - Profile: default - Extending: None - Workspace: /tmp/path/to/my_catkin_ws - Source Space: [exists] /tmp/path/to/my_catkin_ws/src - Build Space: [missing] /tmp/path/to/my_catkin_ws/build - Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel - Install Space: [missing] /tmp/path/to/my_catkin_ws/install - DESTDIR: None - -------------------------------------------------------------- - Isolate Develspaces: False - Install Packages: False - Isolate Installs: False - -------------------------------------------------------------- - Additional CMake Args: None - Additional Make Args: None - Additional catkin Make Args: None - -------------------------------------------------------------- - Whitelisted Packages: None - Blacklisted Packages: None - -------------------------------------------------------------- - Workspace configuration appears valid. - -------------------------------------------------------------- - Found '36' packages in 0.0 seconds. - Packages to be built: - - catkin (catkin) - - genmsg (catkin) - - gencpp (catkin) - - genlisp (catkin) - - genpy (catkin) - - console_bridge (cmake) - - cpp_common (catkin) - - message_generation (catkin) - - message_runtime (catkin) - - ros_tutorials (metapackage) - - rosbuild (catkin) - - rosclean (catkin) - - roscpp_traits (catkin) - - rosgraph (catkin) - - roslang (catkin) - - roslaunch (catkin) - - rosmaster (catkin) - - rospack (catkin) - - roslib (catkin) - - rosparam (catkin) - - rospy (catkin) - - rostime (catkin) - - roscpp_serialization (catkin) - - rosunit (catkin) - - rosconsole (catkin) - - rostest (catkin) - - std_msgs (catkin) - - geometry_msgs (catkin) - - rosgraph_msgs (catkin) - - std_srvs (catkin) - - xmlrpcpp (catkin) - - roscpp (catkin) - - roscpp_tutorials (catkin) - - rosout (catkin) - - rospy_tutorials (catkin) - - turtlesim (catkin) - Total packages: 36 +.. literalinclude:: ../examples/ros_tutorials_ws/2_dry_run.bash + :language: bash In addition to the listing the package names and in which order they would be -built, it also displays the buildtool type of each package. Among those listed -above are: +built, it also displays the build type of each package. - * **catkin** -- A CMake package which uses Catkin - * **cmake** -- A "vanilla" CMake package - * **metapackage** -- A package which contains no build products, but just groups - other packages together for distribution +.. raw:: html + +
Building a Workspace -------------------- @@ -115,69 +44,16 @@ Building a Workspace When no packages are given as arguments, ``catkin build`` builds the entire workspace. It automatically creates directories for a **build space** and a **devel space**: -.. code-block:: bash +.. literalinclude:: ../examples/ros_tutorials_ws/3_build.bash + :language: bash - $ catkin build - Creating buildspace directory, '/tmp/path/to/my_catkin_ws/build' - -------------------------------------------------------------- - Profile: default - Extending: None - Workspace: /tmp/path/to/my_catkin_ws - Source Space: [exists] /tmp/path/to/my_catkin_ws/src - Build Space: [missing] /tmp/path/to/my_catkin_ws/build - Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel - Install Space: [missing] /tmp/path/to/my_catkin_ws/install - DESTDIR: None - -------------------------------------------------------------- - Isolate Develspaces: False - Install Packages: False - Isolate Installs: False - -------------------------------------------------------------- - Additional CMake Args: None - Additional Make Args: None - Additional catkin Make Args: None - -------------------------------------------------------------- - Whitelisted Packages: None - Blacklisted Packages: None - -------------------------------------------------------------- - Workspace configuration appears valid. - -------------------------------------------------------------- - Found '36' packages in 0.0 seconds. - Starting ==> catkin - Starting ==> console_bridge - Finished <== catkin [ 2.4 seconds ] - - .... - - [build] Finished. - [build] Runtime: 3 minutes and 54.6 seconds - -After the build finishes, the **build space** contains directories containing the intermediate build products for each package, and the **devel space** contains an FHS layout into which all the final build products are written. +.. raw:: html -.. code-block:: bash +
- $ ls ./* - ./build: - catkin genlisp message_runtime roscpp - rosgraph_msgs rosout rostest turtlesim - build_logs genmsg ros_tutorials - roscpp_serialization roslang rospack rostime - xmlrpcpp console_bridge genpy rosbuild - roscpp_traits roslaunch rosparam rosunit - cpp_common geometry_msgs rosclean - roscpp_tutorials roslib rospy std_msgs - gencpp message_generation rosconsole rosgraph - rosmaster rospy_tutorials std_srvs - - ./devel: - _setup_util.py bin env.sh etc include - lib setup.bash setup.sh setup.zsh share - - ./src: - catkin console_bridge genlisp genpy - message_runtime ros_comm roscpp_core std_msgs - common_msgs gencpp genmsg message_generation - ros ros_tutorials rospack +After the build finishes, the **build space** contains directories containing +the intermediate build products for each package, and the **devel space** +contains an FHS layout into which all the final build products are written. .. note:: @@ -230,9 +106,9 @@ like the following for the ``genmsg`` package: .. code-block:: none ... - Starting >>> genmsg + Starting >>> {JOB} ... - Finished <<< genmsg [ 0.1 seconds ] + Finished <<< {JOB} [ {TIME} seconds ] ... Error messages are printed whenever a build job writes to ``stderr``. @@ -240,18 +116,16 @@ In such cases, the ``build`` verb will automatically print the captured ``stderr .. code-block:: none - ... ____________________________________________________________________________ - Warnings << rospack:make /path/to/my_catkin_ws/build/_logs/rospack/build.make.000.log - In file included from /usr/include/python2.7/Python.h:8:0, - from /path/to/my_catkin_ws/src/rospack/src/rospack.cpp:71: - /usr/include/python2.7/pyconfig.h:1161:0: warning: "_POSIX_C_SOURCE" redefined [enabled by default] - /usr/include/features.h:164:0: note: this is the location of the previous definition - /usr/include/python2.7/pyconfig.h:1183:0: warning: "_XOPEN_SOURCE" redefined [enabled by default] - /usr/include/features.h:166:0: note: this is the location of the previous definition + Warnings << {JOB}:{STAGE} {LOGFILE PATH} + {WARNINGS} + {REPRODUCTION COMMAND} ............................................................................ - Finished <<< rospack [ 11.7 seconds ] - ... + Finished << {JOB} [ {TIME} seconds ] + +.. raw:: html + +
Note that the first line displays the path to the interleaved log file, which persists until the build space is cleaned. Additionally, if a package fails, the output to ``stderr`` is printed under the ``Errors`` header. @@ -259,77 +133,32 @@ Additionally, if a package fails, the output to ``stderr`` is printed under the .. code-block:: none ____________________________________________________________________________ - Errors << catkin_pkg_make_err:make /home/jbohren/ws/catkin_tools_test_ws/build/_logs/catkin_pkg_make_err/build.make.062.log - /home/jbohren/ws/catkin_tools_test_ws/src/catkin_pkg_make_err/main.cpp: In function ‘int main(int, char**)’: - /home/jbohren/ws/catkin_tools_test_ws/src/catkin_pkg_make_err/main.cpp:3:3: error: expected ‘,’ or ‘;’ before ‘return’ - make[2]: *** [CMakeFiles/main.dir/main.cpp.o] Error 1 - make[1]: *** [CMakeFiles/main.dir/all] Error 2 - make: *** [all] Error 2 + Errors << {JOB}:{STAGE} {LOGFILE PATH} + {ERRORS} + {REPRODUCTION COMMAND} ............................................................................ - Failed << catkin_pkg_make_err:make [ Exited with code 2 ] + Failed << {JOB}:{STAGE} [ Exited with code {EXIT CODE} ] + Failed << {JOB} [ {TIME} seconds ] + +.. raw:: html + +
All of the messages from the underlying jobs can be shown when using the ``-v`` or ``--verbose`` option. This will print the normal messages when a build job starts and finishes as well as the interleaved output to ``stdout`` and ``stderr`` from each build command in a block. -.. code-block:: none +.. raw:: html + +
+ +All output can be printed interleaved with the ``--interleave`` option. In this +case, each line is prefixed with the job and stage from which it came. + +.. raw:: html - Starting >>> genmsg - Starting >> genmsg:mkdir - Finished << genmsg:mkdir - Starting >> genmsg:envgen - Finished << genmsg:envgen - Starting >> genmsg:cmake - Subprocess > genmsg:cmake `cd /path/to/my_catkin_ws/build/genmsg && /path/to/my_catkin_ws/build/genmsg/build_env.sh /usr/bin/cmake /path/to/my_catkin_ws/src/genmsg --no-warn-unused-cli -DCATKIN_DEVEL_PREFIX=/path/to/my_catkin_ws/devel -DCMAKE_INSTALL_PREFIX=/path/to/my_catkin_ws/install` - Output << genmsg:cmake /path/to/my_catkin_ws/build/_logs/genmsg/build.cmake.000.log - Not searching for unused variables given on the command line. - Re-run cmake no build system arguments - -- The C compiler identification is GNU - -- The CXX compiler identification is GNU - -- Check for working C compiler: /usr/bin/gcc - -- Check for working C compiler: /usr/bin/gcc -- works - -- Detecting C compiler ABI info - -- Detecting C compiler ABI info - done - -- Check for working CXX compiler: /usr/bin/c++ - -- Check for working CXX compiler: /usr/bin/c++ -- works - -- Detecting CXX compiler ABI info - -- Detecting CXX compiler ABI info - done - -- Using CATKIN_DEVEL_PREFIX: /path/to/my_catkin_ws/devel - -- Using CMAKE_PREFIX_PATH: /path/to/my_catkin_ws/smach/devel;/opt/ros/hydro - -- This workspace overlays: /path/to/my_catkin_ws/smach/devel;/opt/ros/hydro - -- Found PythonInterp: /usr/bin/python (found version "2.7.3") - -- Using PYTHON_EXECUTABLE: /usr/bin/python - -- Python version: 2.7 - -- Using Debian Python package layout - -- Using CATKIN_ENABLE_TESTING: ON - -- Call enable_testing() - -- Using CATKIN_TEST_RESULTS_DIR: /path/to/my_catkin_ws/build/genmsg/test_results - -- Looking for include files CMAKE_HAVE_PTHREAD_H - -- Looking for include files CMAKE_HAVE_PTHREAD_H - found - -- Looking for pthread_create in pthreads - -- Looking for pthread_create in pthreads - not found - -- Looking for pthread_create in pthread - -- Looking for pthread_create in pthread - found - -- Found Threads: TRUE - -- Found gtest sources under '/usr/src/gtest': gtests will be built - -- catkin 0.5.90 - -- Configuring done - -- Generating done - -- Build files have been written to: /path/to/my_catkin_ws/build/genmsg - Finished << genmsg:cmake - Starting >> genmsg:make - Subprocess > genmsg:make `cd /path/to/my_catkin_ws/build/genmsg && /usr/bin/make --jobserver-fds=3,4 -j` - Output << genmsg:make /path/to/my_catkin_ws/build/_logs/genmsg/build.make.000.log - /usr/bin/cmake -H/path/to/my_catkin_ws/src/genmsg -B/path/to/my_catkin_ws/build/genmsg --check-build-system CMakeFiles/Makefile.cmake 0 - /usr/bin/cmake -E cmake_progress_start /path/to/my_catkin_ws/build/genmsg/CMakeFiles /path/to/my_catkin_ws/build/genmsg/CMakeFiles/progress.marks - /usr/bin/make -f CMakeFiles/Makefile2 all - make[1]: Entering directory `/path/to/my_catkin_ws/build/genmsg' - make[1]: Nothing to be done for `all'. - make[1]: Leaving directory `/path/to/my_catkin_ws/build/genmsg' - /usr/bin/cmake -E cmake_progress_start /path/to/my_catkin_ws/build/genmsg/CMakeFiles 0 - Finished << genmsg:make - Finished <<< genmsg [ 2.0 seconds ] +
Build Summary ------------- @@ -370,113 +199,75 @@ Consider a Catkin workspace with a **source space** populated with the following Building Specific Packages -------------------------- -In addition to the usage above, the ``--dry-run`` option will show what the behavior of ``catkin build`` will be with various other options. -For example, the following will happen when you specify a single package to build: +Specific packages can also be built by specifying them as positional arguments +after the ``build`` verb: -.. code-block:: bash +.. literalinclude:: ../examples/ros_tutorials_ws/6_build_partial.bash + :language: bash + +.. raw:: html - $ catkin build roscpp_tutorials --dry-run - .... - Found '36' packages in 0.1 seconds. - Packages to be built: - - catkin (catkin) - - genmsg (catkin) - - gencpp (catkin) - - genlisp (catkin) - - genpy (catkin) - - console_bridge (cmake) - - cpp_common (catkin) - - message_generation (catkin) - - message_runtime (catkin) - - rosbuild (catkin) - - roscpp_traits (catkin) - - roslang (catkin) - - rospack (catkin) - - roslib (catkin) - - rostime (catkin) - - roscpp_serialization (catkin) - - rosunit (catkin) - - rosconsole (catkin) - - std_msgs (catkin) - - rosgraph_msgs (catkin) - - xmlrpcpp (catkin) - - roscpp (catkin) - - roscpp_tutorials (catkin) - Total packages: 23 - -As shown above, only 23 packages (``roscpp_tutorials`` and its dependencies), -of the total 36 packages would be built. +
+ +As shown above, only 4 packages (``roslib`` and its dependencies), of the total +36 packages would be built. Context-Aware Building ---------------------- -In addition to building all packages or specified packages with various dependency requirements, ``catkin build`` can also determine the package containing the current working directory. -This is equivalent to specifying the name of the package on the command line, and is done by passing the ``--this`` option to ``catkin build`` like the following: +In addition to building all packages or specified packages with various +dependency requirements, ``catkin build`` can also determine the package +containing the current working directory. This is equivalent to specifying the +name of the package on the command line, and is done by passing the ``--this`` +option to ``catkin build`` like the following: -.. code-block:: bash +.. literalinclude:: ../examples/ros_tutorials_ws/7_build_this.bash + :language: bash - $ cd /tmp/path/to/my_catkin_ws/src/roscpp_tutorials - $ catkin build --this --dry-run - .... - Found '36' packages in 0.0 seconds. - Packages to be built: - - roscpp_tutorials (catkin) - Total packages: 1 +.. raw:: html + +
Skipping Packages ----------------- -Suppose you built every package up to ``roscpp_tutorials``, but that package had a build error. -After fixing the error, you could run the same build command again, but the ``build`` verb provides an option to save time in this situation. -If re-started from the beginning, none of the products of the dependencies of ``roscpp_tutorials`` would be re-built, but it would still take some time for the underlying byuildsystem to verify that for each package. +Suppose you built every package up to ``roslib``, but that package +had a build error. +After fixing the error, you could run the same build command again, but the +``build`` verb provides an option to save time in this situation. +If re-started from the beginning, none of the products of the dependencies of +``roslib`` would be re-built, but it would still take some time for +the underlying byuildsystem to verify that for each package. Those checks could be skipped, however, by jumping directly to a given package. -You could use the ``--start-with`` option to continue the build where you left off after fixing the problem. (The following example uses the ``--dry-run`` option again to preview the behavior): +You could use the ``--start-with`` option to continue the build where you left +off after fixing the problem. -.. code-block:: bash +.. literalinclude:: ../examples/ros_tutorials_ws/8_build_start_with.bash + :language: bash + +.. raw:: html + +
+ +.. note:: - $ catkin build roscpp_tutorials --start-with roscpp_tutorials --dry-run - .... - Found '36' packages in 0.0 seconds. - Packages to be built: - (skip) catkin (catkin) - (skip) genmsg (catkin) - (skip) gencpp (catkin) - (skip) genlisp (catkin) - (skip) genpy (catkin) - (skip) console_bridge (cmake) - (skip) cpp_common (catkin) - (skip) message_generation (catkin) - (skip) message_runtime (catkin) - (skip) rosbuild (catkin) - (skip) roscpp_traits (catkin) - (skip) roslang (catkin) - (skip) rospack (catkin) - (skip) roslib (catkin) - (skip) rostime (catkin) - (skip) roscpp_serialization (catkin) - (skip) rosunit (catkin) - (skip) rosconsole (catkin) - (skip) std_msgs (catkin) - (skip) rosgraph_msgs (catkin) - (skip) xmlrpcpp (catkin) - (skip) roscpp (catkin) - ------ roscpp_tutorials (catkin) - Total packages: 23 - -However, you should be careful when using the ``--start-with`` option, as ``catkin build`` will assume that all dependencies leading up to that package have already been successfully built. + ``catkin build`` will assume that all dependencies leading up to the package + specified with the ``--start-with`` option have already been successfully + built. + +Building Single Packages +------------------------ If you're only interested in building a *single* package in a workspace, you can also use the ``--no-deps`` option along with a package name. This will skip all of the package's dependencies, build the given package, and then exit. -.. code-block:: bash +.. literalinclude:: ../examples/ros_tutorials_ws/9_build_no_deps.bash + :language: bash - $ catkin build roscpp_tutorials --no-deps roscpp_tutorials --dry-run - .... - Found '36' packages in 0.0 seconds. - Packages to be built: - - roscpp_tutorials (catkin) - Total packages: 1 +.. raw:: html + +
Building and Running Tests ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -609,128 +400,5 @@ is used, you can specifiy: Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: text - - usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE] - [--dry-run] [--get-env PKGNAME] [--this] [--no-deps] - [--unbuilt] [--start-with PKGNAME | --start-with-this] - [--continue-on-failure] [--force-cmake] [--pre-clean] - [--no-install-lock] [--save-config] [-j JOBS] - [-p PACKAGE_JOBS] [--jobserver | --no-jobserver] - [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...] - | --no-cmake-args] [--make-args ARG [ARG ...] | - --no-make-args] [--catkin-make-args ARG [ARG ...] | - --no-catkin-make-args] [--verbose] [--interleave-output] - [--no-status] [--summarize] [--no-summarize] - [--override-build-tool-check] - [--limit-status-rate LIMIT_STATUS_RATE] [--no-notify] - [PKGNAME [PKGNAME ...]] - - Build one or more packages in a catkin workspace. This invokes `CMake`, - `make`, and optionally `make install` for either all or the specified packages - in a catkin workspace. Arguments passed to this verb can temporarily override - persistent options stored in the catkin profile config. If you want to save - these options, use the --save-config argument. To see the current config, use - the `catkin config` command. - - optional arguments: - -h, --help show this help message and exit - --workspace WORKSPACE, -w WORKSPACE - The path to the catkin_tools workspace or a directory - contained within it (default: ".") - --profile PROFILE The name of a config profile to use (default: active - profile) - --dry-run, -n List the packages which will be built with the given - arguments without building them. - --get-env PKGNAME Print the environment in which PKGNAME is built to - stdout. - - Packages: - Control which packages get built. - - PKGNAME Workspace packages to build, package dependencies are - built as well unless --no-deps is used. If no packages - are given, then all the packages are built. - --this Build the package containing the current working - directory. - --no-deps Only build specified packages, not their dependencies. - --unbuilt Build packages which have yet to be built. - --start-with PKGNAME Build a given package and those which depend on it, - skipping any before it. - --start-with-this Similar to --start-with, starting with the package - containing the current directory. - --continue-on-failure, -c - Try to continue building packages whose dependencies - built successfully even if some other requested - packages fail to build. - - Build: - Control the build behavior. - - --force-cmake Runs cmake explicitly for each catkin package. - --pre-clean Runs `make clean` before building each package. - --no-install-lock Prevents serialization of the install steps, which is - on by default to prevent file install collisions - - Config: - Parameters for the underlying build system. - - --save-config Save any configuration options in this section for the - next build invocation. - -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across - active packages. (default is cpu count) - -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS - Maximum number of packages allowed to be built in - parallel (default is cpu count) - --jobserver Use the internal GNU Make job server which will limit - the number of Make jobs across all active packages. - --no-jobserver Disable the internal GNU Make job server, and use an - external one (like distcc, for example). - --env-cache Re-use cached environment variables when re-sourcing a - resultspace that has been loaded at a different stage - in the task. - --no-env-cache Don't cache environment variables when re-sourcing the - same resultspace. - --cmake-args ARG [ARG ...] - Arbitrary arguments which are passes to CMake. It - collects all of following arguments until a "--" is - read. - --no-cmake-args Pass no additional arguments to CMake. - --make-args ARG [ARG ...] - Arbitrary arguments which are passes to make.It - collects all of following arguments until a "--" is - read. - --no-make-args Pass no additional arguments to make (does not affect - --catkin-make-args). - --catkin-make-args ARG [ARG ...] - Arbitrary arguments which are passes to make but only - for catkin packages.It collects all of following - arguments until a "--" is read. - --no-catkin-make-args - Pass no additional arguments to make for catkin - packages (does not affect --make-args). - - Interface: - The behavior of the command-line interface. - - --verbose, -v Print output from commands in ordered blocks once the - command finishes. - --interleave-output, -i - Prevents ordering of command output when multiple - commands are running at the same time. - --no-status Suppresses status line, useful in situations where - carriage return is not properly supported. - --summarize, --summary, -s - Adds a build summary to the end of a build; defaults - to on with --continue-on-failure, off otherwise - --no-summarize, --no-summary - Explicitly disable the end of build summary - --override-build-tool-check - use to override failure due to using differnt build - tools on the same workspace. - --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE - Limit the update rate of the status bar to this - frequency. Zero means unlimited. Must be positive, - default is 10 Hz. - --no-notify Suppresses system pop-up notification. - +.. literalinclude:: cli/catkin_build.txt + :language: text diff --git a/docs/verbs/catkin_clean.rst b/docs/verbs/catkin_clean.rst index fd634041..3bc0d933 100644 --- a/docs/verbs/catkin_clean.rst +++ b/docs/verbs/catkin_clean.rst @@ -14,36 +14,5 @@ workspace's metadata directory. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: text - - usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE] [-a] [-b] - [-d] [-i] [-c] [-o] - - Deletes various products of the build verb. - - optional arguments: - -h, --help show this help message and exit - --workspace WORKSPACE, -w WORKSPACE - The path to the catkin_tools workspace or a directory - contained within it (default: ".") - --profile PROFILE The name of a config profile to use (default: active - profile) - - Basic: - Clean workspace subdirectories. - - -a, --all Remove all of the *spaces associated with the given or - active profile. This will remove everything but the - source space and the hidden .catkin_tools directory. - -b, --build Remove the buildspace. - -d, --devel Remove the develspace. - -i, --install Remove the installspace. - - Advanced: - Clean only specific parts of the workspace. - - -c, --cmake-cache Clear the CMakeCache for each package, but leave build - and devel spaces. - -o, --orphans Remove only build directories whose source packages - are no longer enabled or in the source space. This - might require --force-cmake on the next build. +.. literalinclude:: cli/catkin_clean.txt + :language: text diff --git a/docs/verbs/catkin_config.rst b/docs/verbs/catkin_config.rst index ba1893a7..59cc766f 100644 --- a/docs/verbs/catkin_config.rst +++ b/docs/verbs/catkin_config.rst @@ -175,7 +175,7 @@ whitelisted packages. To set the whitelist, you can call the following command: -.. code-black:: text +.. code-block:: text catkin config --whitelist foo bar @@ -196,7 +196,7 @@ packages will not be built even if another package in the workspace depends on t To set the blacklist, you can call the following command: -.. code-black:: text +.. code-block:: text catkin config --blacklist baz @@ -223,151 +223,5 @@ for workspaces where many packages are already built. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: text - - usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE] - [--append-args | --remove-args] [--init] - [--extend EXTEND_PATH | --no-extend] [--mkdirs] - [--whitelist PKG [PKG ...] | --no-whitelist] - [--blacklist PKG [PKG ...] | --no-blacklist] - [-s SOURCE_SPACE | --default-source-space] - [-b BUILD_SPACE | --default-build-space] - [-d DEVEL_SPACE | --default-devel-space] - [-i INSTALL_SPACE | --default-install-space] - [-x SPACE_SUFFIX] - [--merge-devel | --link-devel | --isolate-devel] - [--install | --no-install] - [--isolate-install | --merge-install] [-j JOBS] - [-p PACKAGE_JOBS] [--jobserver | --no-jobserver] - [--env-cache | --no-env-cache] - [--cmake-args ARG [ARG ...] | --no-cmake-args] - [--make-args ARG [ARG ...] | --no-make-args] - [--catkin-make-args ARG [ARG ...] | - --no-catkin-make-args] - - This verb is used to configure a catkin workspace's configuration and layout. - Calling `catkin config` with no arguments will display the current config and - affect no changes if a config already exists for the current workspace and - profile. - - optional arguments: - -h, --help show this help message and exit - --workspace WORKSPACE, -w WORKSPACE - The path to the catkin_tools workspace or a directory - contained within it (default: ".") - --profile PROFILE The name of a config profile to use (default: active - profile) - - Behavior: - Options affecting argument handling. - - --append-args, -a For list-type arguments, append elements. - --remove-args, -r For list-type arguments, remove elements. - - Workspace Context: - Options affecting the context of the workspace. - - --init Initialize a workspace if it does not yet exist. - --extend EXTEND_PATH, -e EXTEND_PATH - Explicitly extend the result-space of another catkin - workspace, overriding the value of $CMAKE_PREFIX_PATH. - --no-extend Un-set the explicit extension of another workspace as - set by --extend. - --mkdirs Create directories required by the configuration (e.g. - source space) if they do not already exist. - - Package Build Defaults: - Packages to include or exclude from default build behavior. - - --whitelist PKG [PKG ...] - Set the packages on the whitelist. If the whitelist is - non-empty, only the packages on the whitelist are - built with a bare call to `catkin build`. - --no-whitelist Clear all packages from the whitelist. - --blacklist PKG [PKG ...] - Set the packages on the blacklist. Packages on the - blacklist are not built with a bare call to `catkin - build`. - --no-blacklist Clear all packages from the blacklist. - - Spaces: - Location of parts of the catkin workspace. - - -s SOURCE_SPACE, --source-space SOURCE_SPACE - The path to the source space. - --default-source-space - Use the default path to the source space ("src") - -b BUILD_SPACE, --build-space BUILD_SPACE - The path to the build space. - --default-build-space - Use the default path to the build space ("build") - -d DEVEL_SPACE, --devel-space DEVEL_SPACE - Sets the target devel space - --default-devel-space - Sets the default target devel space ("devel") - -i INSTALL_SPACE, --install-space INSTALL_SPACE - Sets the target install space - --default-install-space - Sets the default target install space ("install") - -x SPACE_SUFFIX, --space-suffix SPACE_SUFFIX - Suffix for build, devel, and install space if they are - not otherwise explicitly set. - - Devel Space: - Options for configuring the structure of the devel space. - - --merge-devel Build products from each catkin package into a single - merged devel spaces. - --link-devel Build products from each catkin package into isolated - spaces, then symbolically link them into a merged - devel space. - --isolate-devel Build products from each catkin package into isolated - devel spaces. - - Install Space: - Options for configuring the structure of the install space. - - --install Causes each package to be installed to the install - space. - --no-install Disables installing each package into the install - space. - --isolate-install Install each catkin package into a separate install - space. - --merge-install Install each catkin package into a single merged - install space. - - Build Options: - Options for configuring the way packages are built. - - -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across - active packages. (default is cpu count) - -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS - Maximum number of packages allowed to be built in - parallel (default is cpu count) - --jobserver Use the internal GNU Make job server which will limit - the number of Make jobs across all active packages. - --no-jobserver Disable the internal GNU Make job server, and use an - external one (like distcc, for example). - --env-cache Re-use cached environment variables when re-sourcing a - resultspace that has been loaded at a different stage - in the task. - --no-env-cache Don't cache environment variables when re-sourcing the - same resultspace. - --cmake-args ARG [ARG ...] - Arbitrary arguments which are passes to CMake. It - collects all of following arguments until a "--" is - read. - --no-cmake-args Pass no additional arguments to CMake. - --make-args ARG [ARG ...] - Arbitrary arguments which are passes to make.It - collects all of following arguments until a "--" is - read. - --no-make-args Pass no additional arguments to make (does not affect - --catkin-make-args). - --catkin-make-args ARG [ARG ...] - Arbitrary arguments which are passes to make but only - for catkin packages.It collects all of following - arguments until a "--" is read. - --no-catkin-make-args - Pass no additional arguments to make for catkin - packages (does not affect --make-args). +.. literalinclude:: cli/catkin_config.txt + :language: text diff --git a/docs/verbs/catkin_create.rst b/docs/verbs/catkin_create.rst index 58782fe4..d2e04042 100644 --- a/docs/verbs/catkin_create.rst +++ b/docs/verbs/catkin_create.rst @@ -6,71 +6,12 @@ This verb enables you to quickly create workspace elements like boilerplate Catk Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: text +.. literalinclude:: cli/catkin_create.txt + :language: text - usage: catkin create [-h] {pkg} ... +``catkin create pkg`` +------------------------- - Creates a catkin workspace +.. literalinclude:: cli/catkin_create_pkg.txt + :language: text - positional arguments: - {pkg} sub-command help - pkg Create a catkin package. - - optional arguments: - -h, --help show this help message and exit - -.. code-block:: text - - usage: catkin create pkg [-h] [--rosdistro ROSDISTRO] [-v MAJOR.MINOR.PATCH] - [-l LICENSE] [-m NAME EMAIL] [-a NAME EMAIL] - [-d DESCRIPTION] [--catkin-deps [DEP [DEP ...]]] - [--system-deps [DEP [DEP ...]]] - [--boost-components [COMP [COMP ...]]] - PKGNAME - - Create a new Catkin package. Note that while the default options used by this - command are sufficient for prototyping and local usage, it is important that - any publically-available packages have a valid license and a valid maintainer - e-mail address. - - positional arguments: - PKGNAME The name of the package to create. This name should be - completely lower-case with individual words separated - by undercores. - - optional arguments: - -h, --help show this help message and exit - --rosdistro ROSDISTRO - The ROS distro (default: environment variable - ROS_DISTRO if defined) - - Package Metadata: - -v MAJOR.MINOR.PATCH, --version MAJOR.MINOR.PATCH - Initial package version. (default 0.0.0) - -l LICENSE, --license LICENSE - The software license under which the code is - distributed, such as BSD, MIT, GPLv3, or others. - (default: "TODO") - -m NAME EMAIL, --maintainer NAME EMAIL - A maintainer who is responsible for the package. - (default: [username, username@todo.todo]) (multiple - allowed) - -a NAME EMAIL, --author NAME EMAIL - An author who contributed to the package. (default: no - additional authors) (multiple allowed) - -d DESCRIPTION, --description DESCRIPTION - Description of the package. (default: empty) - - Package Dependencies: - --catkin-deps [DEP [DEP ...]], -c [DEP [DEP ...]] - The names of one or more Catkin dependencies. These - are Catkin-based packages which are either built as - source or installed by your system's package manager. - --system-deps [DEP [DEP ...]], -s [DEP [DEP ...]] - The names of one or more system dependencies. These - are other packages installed by your operating - system's package manager. - - C++ Options: - --boost-components [COMP [COMP ...]] - One or more boost components used by the package. diff --git a/docs/verbs/catkin_env.rst b/docs/verbs/catkin_env.rst new file mode 100644 index 00000000..7ab99a86 --- /dev/null +++ b/docs/verbs/catkin_env.rst @@ -0,0 +1,14 @@ +``catkin env`` -- Environment Utility +===================================== + +The ``env`` verb can be used to both print the current environment variables +and run a command in a modified environment. This verb is supplied as a +cross-platform alternative to the UNIX ``env`` command or the ``cmake -E +environment`` command. It is primarily used in the build stage command +reproduction. + +Full Command-Line Interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. literalinclude:: cli/catkin_env.txt + :language: text diff --git a/docs/verbs/catkin_init.rst b/docs/verbs/catkin_init.rst index 71f20408..ce1b766b 100644 --- a/docs/verbs/catkin_init.rst +++ b/docs/verbs/catkin_init.rst @@ -19,17 +19,5 @@ of that workspace. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: text - - usage: catkin init [-h] [--workspace WORKSPACE] [--profile PROFILE] [--reset] - - Initializes a given folder as a catkin workspace - - optional arguments: - -h, --help show this help message and exit - --workspace WORKSPACE, -w WORKSPACE - The path to the catkin_tools workspace or a directory - contained within it (default: ".") - --reset Reset (delete) all of the metadata for the given - workspace. - +.. literalinclude:: cli/catkin_init.txt + :language: text diff --git a/docs/verbs/catkin_list.rst b/docs/verbs/catkin_list.rst index 45ccfc23..730d7121 100644 --- a/docs/verbs/catkin_list.rst +++ b/docs/verbs/catkin_list.rst @@ -22,23 +22,5 @@ pipe-based programs. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: text - - usage: catkin list [-h] [--deps] [--depends-on [DEPENDS_ON [DEPENDS_ON ...]]] - [folders [folders ...]] - - Lists catkin packages in the workspace or other arbitray folders. - - positional arguments: - folders Folders in which to find packages. (default: cwd) - - optional arguments: - -h, --help show this help message and exit - --deps, --dependencies - List dependencies of each package. - --depends-on [DEPENDS_ON [DEPENDS_ON ...]] - List all packages that depend on supplied argument - package(s). - --quiet Don't print out detected package warnings. - --unformatted, -u Print list without punctuation and additional details. - +.. literalinclude:: cli/catkin_list.txt + :language: text diff --git a/docs/verbs/catkin_locate.rst b/docs/verbs/catkin_locate.rst index d954bcd9..f4993c35 100644 --- a/docs/verbs/catkin_locate.rst +++ b/docs/verbs/catkin_locate.rst @@ -8,41 +8,5 @@ directories in the workspace. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: text - - usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e] [-r] - [-s | -b | -d | -i] - [PACKAGE] - - Get the paths to various locations in a workspace. - - optional arguments: - -h, --help show this help message and exit - --workspace WORKSPACE, -w WORKSPACE - The path to the catkin_tools workspace or a directory - contained within it (default: ".") - --profile PROFILE The name of a config profile to use (default: active - profile) - - Behavior: - -e, --existing-only Only print paths to existing directories. - -r, --relative Print relative paths instead of the absolute paths. - - Sub-Space Options: - Get the absolute path to one of the following locations in the given - workspace with the given profile. - - -s, --src Get the path to the source space. - -b, --build Get the path to the build space. - -d, --devel Get the path to the devel space. - -i, --install Get the path to the install space. - - Package Directories: - Get the absolute path to package directories in the given workspace and - sub-space. By default this will output paths in the workspace's source - space. If the -b (--build) flag is given, it will output the path to the - package's build directory. If the -d or -i (--devel or --install) flags - are given, it will output the path to the package's share directory in - that space. - - PACKAGE The name of a package to locate. +.. literalinclude:: cli/catkin_locate.txt + :language: text diff --git a/docs/verbs/catkin_profile.rst b/docs/verbs/catkin_profile.rst index 15602971..386d53cb 100644 --- a/docs/verbs/catkin_profile.rst +++ b/docs/verbs/catkin_profile.rst @@ -170,93 +170,36 @@ The ``profile`` verb can also be used for renaming and removing profiles: Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: text - - usage: catkin profile [-h] [--workspace WORKSPACE] - {list,set,add,rename,remove} ... - - Manage metadata profiles for a catkin workspace - - positional arguments: - {list,set,add,rename,remove} - sub-command help - list List the available profiles. - set Set the active profile by name. - add Add a new profile by name. - rename Rename a given profile. - remove Remove a profile by name. - - optional arguments: - -h, --help show this help message and exit - --workspace WORKSPACE, -w WORKSPACE - The path to the catkin workspace. Default: current - working directory +.. literalinclude:: cli/catkin_profile.txt + :language: text ``catkin profile list`` ----------------------- -.. code-block:: text - - usage: catkin profile list [-h] - - optional arguments: - -h, --help show this help message and exit +.. literalinclude:: cli/catkin_profile_list.txt + :language: text ``catkin profile set`` ----------------------- -.. code-block:: text - - usage: catkin profile set [-h] name - - positional arguments: - name The profile to activate. - - optional arguments: - -h, --help show this help message and exit +.. literalinclude:: cli/catkin_profile_set.txt + :language: text ``catkin profile add`` ----------------------- -.. code-block:: text - - usage: catkin profile add [-h] [-f] [--copy BASE_PROFILE | --copy-active] name - - positional arguments: - name The new profile name. - - optional arguments: - -h, --help show this help message and exit - -f, --force Overwrite an existing profile. - --copy BASE_PROFILE Copy the settings from an existing profile. (default: - None) - --copy-active Copy the settings from the active profile. +.. literalinclude:: cli/catkin_profile_add.txt + :language: text ``catkin profile rename`` ------------------------- -.. code-block:: text - - usage: catkin profile rename [-h] [-f] current_name new_name - - positional arguments: - current_name The current name of the profile to be renamed. - new_name The new name for the profile. - - optional arguments: - -h, --help show this help message and exit - -f, --force Overwrite an existing profile. +.. literalinclude:: cli/catkin_profile_rename.txt + :language: text ``catkin profile remove`` ------------------------- -.. code-block:: text - - usage: catkin profile remove [-h] [name [name ...]] - - positional arguments: - name One or more profile names to remove. - - optional arguments: - -h, --help show this help message and exit +.. literalinclude:: cli/catkin_profile_remove.txt + :language: text diff --git a/docs/verbs/cli/catkin_build.txt b/docs/verbs/cli/catkin_build.txt new file mode 100644 index 00000000..2168ed34 --- /dev/null +++ b/docs/verbs/cli/catkin_build.txt @@ -0,0 +1,122 @@ +usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE] + [--dry-run] [--get-env PKGNAME] [--this] [--no-deps] + [--unbuilt] [--start-with PKGNAME | --start-with-this] + [--continue-on-failure] [--force-cmake] [--pre-clean] + [--no-install-lock] [--save-config] [-j JOBS] + [-p PACKAGE_JOBS] [--jobserver | --no-jobserver] + [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...] + | --no-cmake-args] [--make-args ARG [ARG ...] | + --no-make-args] [--catkin-make-args ARG [ARG ...] | + --no-catkin-make-args] [--verbose] [--interleave-output] + [--no-status] [--summarize] [--no-summarize] + [--override-build-tool-check] + [--limit-status-rate LIMIT_STATUS_RATE] [--no-notify] + [PKGNAME [PKGNAME ...]] + +Build one or more packages in a catkin workspace. This invokes `CMake`, +`make`, and optionally `make install` for either all or the specified packages +in a catkin workspace. Arguments passed to this verb can temporarily override +persistent options stored in the catkin profile config. If you want to save +these options, use the --save-config argument. To see the current config, use +the `catkin config` command. + +optional arguments: + -h, --help show this help message and exit + --workspace WORKSPACE, -w WORKSPACE + The path to the catkin_tools workspace or a directory + contained within it (default: ".") + --profile PROFILE The name of a config profile to use (default: active + profile) + --dry-run, -n List the packages which will be built with the given + arguments without building them. + --get-env PKGNAME Print the environment in which PKGNAME is built to + stdout. + +Packages: + Control which packages get built. + + PKGNAME Workspace packages to build, package dependencies are + built as well unless --no-deps is used. If no packages + are given, then all the packages are built. + --this Build the package containing the current working + directory. + --no-deps Only build specified packages, not their dependencies. + --unbuilt Build packages which have yet to be built. + --start-with PKGNAME Build a given package and those which depend on it, + skipping any before it. + --start-with-this Similar to --start-with, starting with the package + containing the current directory. + --continue-on-failure, -c + Try to continue building packages whose dependencies + built successfully even if some other requested + packages fail to build. + +Build: + Control the build behavior. + + --force-cmake Runs cmake explicitly for each catkin package. + --pre-clean Runs `make clean` before building each package. + --no-install-lock Prevents serialization of the install steps, which is + on by default to prevent file install collisions + +Config: + Parameters for the underlying build system. + + --save-config Save any configuration options in this section for the + next build invocation. + -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across + active packages. (default is cpu count) + -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS + Maximum number of packages allowed to be built in + parallel (default is cpu count) + --jobserver Use the internal GNU Make job server which will limit + the number of Make jobs across all active packages. + --no-jobserver Disable the internal GNU Make job server, and use an + external one (like distcc, for example). + --env-cache Re-use cached environment variables when re-sourcing a + resultspace that has been loaded at a different stage + in the task. + --no-env-cache Don't cache environment variables when re-sourcing the + same resultspace. + --cmake-args ARG [ARG ...] + Arbitrary arguments which are passes to CMake. It + collects all of following arguments until a "--" is + read. + --no-cmake-args Pass no additional arguments to CMake. + --make-args ARG [ARG ...] + Arbitrary arguments which are passes to make.It + collects all of following arguments until a "--" is + read. + --no-make-args Pass no additional arguments to make (does not affect + --catkin-make-args). + --catkin-make-args ARG [ARG ...] + Arbitrary arguments which are passes to make but only + for catkin packages.It collects all of following + arguments until a "--" is read. + --no-catkin-make-args + Pass no additional arguments to make for catkin + packages (does not affect --make-args). + +Interface: + The behavior of the command-line interface. + + --verbose, -v Print output from commands in ordered blocks once the + command finishes. + --interleave-output, -i + Prevents ordering of command output when multiple + commands are running at the same time. + --no-status Suppresses status line, useful in situations where + carriage return is not properly supported. + --summarize, --summary, -s + Adds a build summary to the end of a build; defaults + to on with --continue-on-failure, off otherwise + --no-summarize, --no-summary + Explicitly disable the end of build summary + --override-build-tool-check + use to override failure due to using differnt build + tools on the same workspace. + --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE + Limit the update rate of the status bar to this + frequency. Zero means unlimited. Must be positive, + default is 10 Hz. + --no-notify Suppresses system pop-up notification. diff --git a/docs/verbs/cli/catkin_clean.txt b/docs/verbs/cli/catkin_clean.txt new file mode 100644 index 00000000..c8d72f66 --- /dev/null +++ b/docs/verbs/cli/catkin_clean.txt @@ -0,0 +1,35 @@ +usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE] [-a] [-b] + [-d] [-i] [-c] [-s] [-o] + +Deletes various products of the build verb. + +optional arguments: + -h, --help show this help message and exit + --workspace WORKSPACE, -w WORKSPACE + The path to the catkin_tools workspace or a directory + contained within it (default: ".") + --profile PROFILE The name of a config profile to use (default: active + profile) + +Basic: + Clean workspace subdirectories. + + -a, --all Remove all of the *spaces associated with the given or + active profile. This will remove everything but the + source space and the hidden .catkin_tools directory. + -b, --build Remove the buildspace. + -d, --devel Remove the develspace. + -i, --install Remove the installspace. + +Advanced: + Clean only specific parts of the workspace. These options will + automatically enable the --force-cmake option for the next build + invocation. + + -c, --cmake-cache Clear the CMakeCache for each package, but leave build + and devel spaces. + -s, --setup-files Clear the catkin-generated files in order to rebase + onto another workspace. + -o, --orphans Remove only build directories whose source packages + are no longer enabled or in the source space. This + might require --force-cmake on the next build. diff --git a/docs/verbs/cli/catkin_config.txt b/docs/verbs/cli/catkin_config.txt new file mode 100644 index 00000000..16df57b9 --- /dev/null +++ b/docs/verbs/cli/catkin_config.txt @@ -0,0 +1,146 @@ +usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE] + [--append-args | --remove-args] [--init] + [--extend EXTEND_PATH | --no-extend] [--mkdirs] + [--whitelist PKG [PKG ...] | --no-whitelist] + [--blacklist PKG [PKG ...] | --no-blacklist] + [-s SOURCE_SPACE | --default-source-space] + [-b BUILD_SPACE | --default-build-space] + [-d DEVEL_SPACE | --default-devel-space] + [-i INSTALL_SPACE | --default-install-space] + [-x SPACE_SUFFIX] + [--merge-devel | --link-devel | --isolate-devel] + [--install | --no-install] + [--isolate-install | --merge-install] [-j JOBS] + [-p PACKAGE_JOBS] [--jobserver | --no-jobserver] + [--env-cache | --no-env-cache] + [--cmake-args ARG [ARG ...] | --no-cmake-args] + [--make-args ARG [ARG ...] | --no-make-args] + [--catkin-make-args ARG [ARG ...] | + --no-catkin-make-args] + +This verb is used to configure a catkin workspace's configuration and layout. +Calling `catkin config` with no arguments will display the current config and +affect no changes if a config already exists for the current workspace and +profile. + +optional arguments: + -h, --help show this help message and exit + --workspace WORKSPACE, -w WORKSPACE + The path to the catkin_tools workspace or a directory + contained within it (default: ".") + --profile PROFILE The name of a config profile to use (default: active + profile) + +Behavior: + Options affecting argument handling. + + --append-args, -a For list-type arguments, append elements. + --remove-args, -r For list-type arguments, remove elements. + +Workspace Context: + Options affecting the context of the workspace. + + --init Initialize a workspace if it does not yet exist. + --extend EXTEND_PATH, -e EXTEND_PATH + Explicitly extend the result-space of another catkin + workspace, overriding the value of $CMAKE_PREFIX_PATH. + --no-extend Un-set the explicit extension of another workspace as + set by --extend. + --mkdirs Create directories required by the configuration (e.g. + source space) if they do not already exist. + +Package Build Defaults: + Packages to include or exclude from default build behavior. + + --whitelist PKG [PKG ...] + Set the packages on the whitelist. If the whitelist is + non-empty, only the packages on the whitelist are + built with a bare call to `catkin build`. + --no-whitelist Clear all packages from the whitelist. + --blacklist PKG [PKG ...] + Set the packages on the blacklist. Packages on the + blacklist are not built with a bare call to `catkin + build`. + --no-blacklist Clear all packages from the blacklist. + +Spaces: + Location of parts of the catkin workspace. + + -s SOURCE_SPACE, --source-space SOURCE_SPACE + The path to the source space. + --default-source-space + Use the default path to the source space ("src") + -b BUILD_SPACE, --build-space BUILD_SPACE + The path to the build space. + --default-build-space + Use the default path to the build space ("build") + -d DEVEL_SPACE, --devel-space DEVEL_SPACE + Sets the target devel space + --default-devel-space + Sets the default target devel space ("devel") + -i INSTALL_SPACE, --install-space INSTALL_SPACE + Sets the target install space + --default-install-space + Sets the default target install space ("install") + -x SPACE_SUFFIX, --space-suffix SPACE_SUFFIX + Suffix for build, devel, and install space if they are + not otherwise explicitly set. + +Devel Space: + Options for configuring the structure of the devel space. + + --merge-devel Build products from each catkin package into a single + merged devel spaces. + --link-devel Build products from each catkin package into isolated + spaces, then symbolically link them into a merged + devel space. + --isolate-devel Build products from each catkin package into isolated + devel spaces. + +Install Space: + Options for configuring the structure of the install space. + + --install Causes each package to be installed to the install + space. + --no-install Disables installing each package into the install + space. + --isolate-install Install each catkin package into a separate install + space. + --merge-install Install each catkin package into a single merged + install space. + +Build Options: + Options for configuring the way packages are built. + + -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across + active packages. (default is cpu count) + -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS + Maximum number of packages allowed to be built in + parallel (default is cpu count) + --jobserver Use the internal GNU Make job server which will limit + the number of Make jobs across all active packages. + --no-jobserver Disable the internal GNU Make job server, and use an + external one (like distcc, for example). + --env-cache Re-use cached environment variables when re-sourcing a + resultspace that has been loaded at a different stage + in the task. + --no-env-cache Don't cache environment variables when re-sourcing the + same resultspace. + --cmake-args ARG [ARG ...] + Arbitrary arguments which are passes to CMake. It + collects all of following arguments until a "--" is + read. + --no-cmake-args Pass no additional arguments to CMake. + --make-args ARG [ARG ...] + Arbitrary arguments which are passes to make.It + collects all of following arguments until a "--" is + read. + --no-make-args Pass no additional arguments to make (does not affect + --catkin-make-args). + --catkin-make-args ARG [ARG ...] + Arbitrary arguments which are passes to make but only + for catkin packages.It collects all of following + arguments until a "--" is read. + --no-catkin-make-args + Pass no additional arguments to make for catkin + packages (does not affect --make-args). diff --git a/docs/verbs/cli/catkin_create.txt b/docs/verbs/cli/catkin_create.txt new file mode 100644 index 00000000..c27585d7 --- /dev/null +++ b/docs/verbs/cli/catkin_create.txt @@ -0,0 +1,10 @@ +usage: catkin create [-h] {pkg} ... + +Creates catkin workspace resources like packages. + +positional arguments: + {pkg} sub-command help + pkg Create a new catkin package. + +optional arguments: + -h, --help show this help message and exit diff --git a/docs/verbs/cli/catkin_create_pkg.txt b/docs/verbs/cli/catkin_create_pkg.txt new file mode 100644 index 00000000..94cd79fc --- /dev/null +++ b/docs/verbs/cli/catkin_create_pkg.txt @@ -0,0 +1,55 @@ +usage: catkin create pkg [-h] [-p PATH] [--rosdistro ROSDISTRO] + [-v MAJOR.MINOR.PATCH] [-l LICENSE] [-m NAME EMAIL] + [-a NAME EMAIL] [-d DESCRIPTION] + [--catkin-deps [DEP [DEP ...]]] + [--system-deps [DEP [DEP ...]]] + [--boost-components [COMP [COMP ...]]] + PKG_NAME [PKG_NAME ...] + +Create a new Catkin package. Note that while the default options used by this +command are sufficient for prototyping and local usage, it is important that +any publically-available packages have a valid license and a valid maintainer +e-mail address. + +positional arguments: + PKG_NAME The name of one or more packages to create. This name + should be completely lower-case with individual words + separated by undercores. + +optional arguments: + -h, --help show this help message and exit + -p PATH, --path PATH The path into which the package should be generated. + --rosdistro ROSDISTRO + The ROS distro (default: environment variable + ROS_DISTRO if defined) + +Package Metadata: + -v MAJOR.MINOR.PATCH, --version MAJOR.MINOR.PATCH + Initial package version. (default 0.0.0) + -l LICENSE, --license LICENSE + The software license under which the code is + distributed, such as BSD, MIT, GPLv3, or others. + (default: "TODO") + -m NAME EMAIL, --maintainer NAME EMAIL + A maintainer who is responsible for the package. + (default: [username, username@todo.todo]) (multiple + allowed) + -a NAME EMAIL, --author NAME EMAIL + An author who contributed to the package. (default: no + additional authors) (multiple allowed) + -d DESCRIPTION, --description DESCRIPTION + Description of the package. (default: empty) + +Package Dependencies: + --catkin-deps [DEP [DEP ...]], -c [DEP [DEP ...]] + The names of one or more Catkin dependencies. These + are Catkin-based packages which are either built as + source or installed by your system's package manager. + --system-deps [DEP [DEP ...]], -s [DEP [DEP ...]] + The names of one or more system dependencies. These + are other packages installed by your operating + system's package manager. + +C++ Options: + --boost-components [COMP [COMP ...]] + One or more boost components used by the package. diff --git a/docs/verbs/cli/catkin_env.txt b/docs/verbs/cli/catkin_env.txt new file mode 100644 index 00000000..9387d5a7 --- /dev/null +++ b/docs/verbs/cli/catkin_env.txt @@ -0,0 +1,20 @@ +usage: catkin env [-h] [-i] [-s] + [NAME=VALUE [NAME=VALUE ...]] [COMMAND] [ARG [ARG ...]] + +Run an arbitrary command in a modified environment. + +positional arguments: + NAME=VALUE Explicitly set environment variables for the + subcommand. These override variables given to stdin. + +optional arguments: + -h, --help show this help message and exit + -i, --ignore-environment + Start with an empty environment. + -s, --stdin Read environment variable definitions from stdin. + Variables should be given in NAME=VALUE format. + +command: + COMMAND Command to run. If omitted, the environment is printed + to stdout. + ARG Arguments to the command. diff --git a/docs/verbs/cli/catkin_init.txt b/docs/verbs/cli/catkin_init.txt new file mode 100644 index 00000000..46f6faa5 --- /dev/null +++ b/docs/verbs/cli/catkin_init.txt @@ -0,0 +1,11 @@ +usage: catkin init [-h] [--workspace WORKSPACE] [--reset] + +Initializes a given folder as a catkin workspace. + +optional arguments: + -h, --help show this help message and exit + --workspace WORKSPACE, -w WORKSPACE + The path to the catkin_tools workspace or a directory + contained within it (default: ".") + --reset Reset (delete) all of the metadata for the given + workspace. diff --git a/docs/verbs/cli/catkin_list.txt b/docs/verbs/cli/catkin_list.txt new file mode 100644 index 00000000..f6206e7b --- /dev/null +++ b/docs/verbs/cli/catkin_list.txt @@ -0,0 +1,25 @@ +usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE] [--deps] + [--depends-on [DEPENDS_ON [DEPENDS_ON ...]]] [--quiet] + [--unformatted] + [folders [folders ...]] + +Lists catkin packages in the workspace or other arbitray folders. + +positional arguments: + folders Folders in which to find packages. (default: workspace + source space) + +optional arguments: + -h, --help show this help message and exit + --workspace WORKSPACE, -w WORKSPACE + The path to the catkin_tools workspace or a directory + contained within it (default: ".") + --profile PROFILE The name of a config profile to use (default: active + profile) + --deps, --dependencies + List dependencies of each package. + --depends-on [DEPENDS_ON [DEPENDS_ON ...]] + List all packages that depend on supplied argument + package(s). + --quiet Don't print out detected package warnings. + --unformatted, -u Print list without punctuation and additional details. diff --git a/docs/verbs/cli/catkin_locate.txt b/docs/verbs/cli/catkin_locate.txt new file mode 100644 index 00000000..4c2de904 --- /dev/null +++ b/docs/verbs/cli/catkin_locate.txt @@ -0,0 +1,38 @@ +usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e] + [-r] [-s | -b | -d | -i] + [PACKAGE] + +Get the paths to various locations in a workspace. + +optional arguments: + -h, --help show this help message and exit + --workspace WORKSPACE, -w WORKSPACE + The path to the catkin_tools workspace or a directory + contained within it (default: ".") + --profile PROFILE The name of a config profile to use (default: active + profile) + +Behavior: + -e, --existing-only Only print paths to existing directories. + -r, --relative Print relative paths instead of the absolute paths. + +Sub-Space Options: + Get the absolute path to one of the following locations in the given + workspace with the given profile. + + -s, --src Get the path to the source space. + -b, --build Get the path to the build space. + -d, --devel Get the path to the devel space. + -i, --install Get the path to the install space. + +Package Directories: + Get the absolute path to package directories in the given workspace and + sub-space. By default this will output paths in the workspace's source + space. If the -b (--build) flag is given, it will output the path to the + package's build directory. If the -d or -i (--devel or --install) flags + are given, it will output the path to the package's share directory in + that space. If no package is provided, the base space paths are printed, + e.g. `catkin locate -s` might return `/path/to/ws/src` and `catkin locate + -s foo` might return `/path/to/ws/src/foo`. + + PACKAGE The name of a package to locate. diff --git a/docs/verbs/cli/catkin_profile.txt b/docs/verbs/cli/catkin_profile.txt new file mode 100644 index 00000000..cb03a277 --- /dev/null +++ b/docs/verbs/cli/catkin_profile.txt @@ -0,0 +1,19 @@ +usage: catkin profile [-h] [--workspace WORKSPACE] + {list,set,add,rename,remove} ... + +Manage config profiles for a catkin workspace. + +positional arguments: + {list,set,add,rename,remove} + sub-command help + list List the available profiles. + set Set the active profile by name. + add Add a new profile by name. + rename Rename a given profile. + remove Remove a profile by name. + +optional arguments: + -h, --help show this help message and exit + --workspace WORKSPACE, -w WORKSPACE + The path to the catkin workspace. Default: current + working directory diff --git a/docs/verbs/cli/catkin_profile_add.txt b/docs/verbs/cli/catkin_profile_add.txt new file mode 100644 index 00000000..f674b89e --- /dev/null +++ b/docs/verbs/cli/catkin_profile_add.txt @@ -0,0 +1,11 @@ +usage: catkin profile add [-h] [-f] [--copy BASE_PROFILE | --copy-active] name + +positional arguments: + name The new profile name. + +optional arguments: + -h, --help show this help message and exit + -f, --force Overwrite an existing profile. + --copy BASE_PROFILE Copy the settings from an existing profile. (default: + None) + --copy-active Copy the settings from the active profile. diff --git a/docs/verbs/cli/catkin_profile_list.txt b/docs/verbs/cli/catkin_profile_list.txt new file mode 100644 index 00000000..1606aa3d --- /dev/null +++ b/docs/verbs/cli/catkin_profile_list.txt @@ -0,0 +1,6 @@ +usage: catkin profile list [-h] [--unformatted] + +optional arguments: + -h, --help show this help message and exit + --unformatted, -u Print profile list without punctuation and additional + details. diff --git a/docs/verbs/cli/catkin_profile_remove.txt b/docs/verbs/cli/catkin_profile_remove.txt new file mode 100644 index 00000000..0fd0b59f --- /dev/null +++ b/docs/verbs/cli/catkin_profile_remove.txt @@ -0,0 +1,7 @@ +usage: catkin profile remove [-h] [name [name ...]] + +positional arguments: + name One or more profile names to remove. + +optional arguments: + -h, --help show this help message and exit diff --git a/docs/verbs/cli/catkin_profile_rename.txt b/docs/verbs/cli/catkin_profile_rename.txt new file mode 100644 index 00000000..d14c12c8 --- /dev/null +++ b/docs/verbs/cli/catkin_profile_rename.txt @@ -0,0 +1,9 @@ +usage: catkin profile rename [-h] [-f] current_name new_name + +positional arguments: + current_name The current name of the profile to be renamed. + new_name The new name for the profile. + +optional arguments: + -h, --help show this help message and exit + -f, --force Overwrite an existing profile. diff --git a/docs/verbs/cli/catkin_profile_set.txt b/docs/verbs/cli/catkin_profile_set.txt new file mode 100644 index 00000000..1add6d6c --- /dev/null +++ b/docs/verbs/cli/catkin_profile_set.txt @@ -0,0 +1,7 @@ +usage: catkin profile set [-h] name + +positional arguments: + name The profile to activate. + +optional arguments: + -h, --help show this help message and exit diff --git a/docs/verbs/cli/dump_cli b/docs/verbs/cli/dump_cli new file mode 100755 index 00000000..1143b024 --- /dev/null +++ b/docs/verbs/cli/dump_cli @@ -0,0 +1,17 @@ +#!/usr/bin/env bash + +catkin build -h > catkin_build.txt +catkin clean -h > catkin_clean.txt +catkin config -h > catkin_config.txt +catkin create -h > catkin_create.txt +catkin create pkg -h > catkin_create_pkg.txt +catkin env -h > catkin_env.txt +catkin init -h > catkin_init.txt +catkin list -h > catkin_list.txt +catkin locate -h > catkin_locate.txt +catkin profile -h > catkin_profile.txt +catkin profile list -h > catkin_profile_list.txt +catkin profile set -h > catkin_profile_set.txt +catkin profile add -h > catkin_profile_add.txt +catkin profile rename -h > catkin_profile_rename.txt +catkin profile remove -h > catkin_profile_remove.txt diff --git a/setup.py b/setup.py index 03414738..224762d1 100644 --- a/setup.py +++ b/setup.py @@ -108,6 +108,7 @@ def run(self): 'notifications/resources/linux/catkin_icon.png', 'notifications/resources/linux/catkin_icon_red.png', 'verbs/catkin_shell_verbs.bash', + 'docs/examples', ] + osx_notification_resources }, data_files=get_data_files(prefix), From 472ead051eefc0f46341b395b8cb9c86b61aa9d8 Mon Sep 17 00:00:00 2001 From: Alexander Schaefer Date: Fri, 26 Feb 2016 08:54:01 +0100 Subject: [PATCH 05/10] Fix some typos. --- docs/mechanics.rst | 14 +++++++------- docs/quick_start.rst | 22 +++++++++++----------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/mechanics.rst b/docs/mechanics.rst index 8943b488..967ebc16 100644 --- a/docs/mechanics.rst +++ b/docs/mechanics.rst @@ -88,7 +88,7 @@ persistent configuration information. This directory contains subdirectories representing different configuration profiles, and inside of each profile directory are YAML files which contain verb-specific metadata. It additionally contains a file which lists the name of -the active configuration profile if it is different than ``default``. +the active configuration profile if it is different from ``default``. Build Log Directory ------------------- @@ -269,7 +269,7 @@ Tango `_. ``pcmi`` later became the ``build`` verb of the ``catkin`` command included in this project. -As such, the principle behavior of the ``build`` verb is to build each +As such, the principal behavior of the ``build`` verb is to build each package in isolation and in topological order while parallelizing the building of packages which do not depend on each other. @@ -318,11 +318,11 @@ containing that setup file to the ``CMAKE_PREFIX_PATH`` environment variable. The next time you initialize a workspace, it will extend the workspace that you previously sourced. -On one hand, this makes it easy and automatic to chain workspaces. At the same -time, however, previous tools like ``catkin_make`` and ``catkin_make_isolated`` -had no easy mechanism for either making it obvious which workspace was being -extended, nor did they provide features to explicitly extend a given workspace. -This means that for users unaware of Catkin's use of ``CMAKE_PREFIX_PATH`` +This makes it easy and automatic to chain workspaces. Previous tools like +``catkin_make`` and ``catkin_make_isolated`` had no easy mechanism for +either making it obvious which workspace was being extended, nor did they +provide features to explicitly extend a given workspace. This means that users +were unaware of Catkin's use of ``CMAKE_PREFIX_PATH``. Since it's not expected that 100% of users will read this section of the documentation, the ``catkin`` program adds both configuration consistency diff --git a/docs/quick_start.rst b/docs/quick_start.rst index e14b8a41..6b9a3df2 100644 --- a/docs/quick_start.rst +++ b/docs/quick_start.rst @@ -4,7 +4,7 @@ Quickstart This chapter gives a high-level overview of how to use ``catkin_tools`` and the ``catkin`` command. This shows how to use the different command verbs to create and manipulate a workspace. For a more in-depth explanation of the mechanics of -catkin workspaces, see :doc:`Workspace Mechanics `, and for thorogh +catkin workspaces, see :doc:`Workspace Mechanics `, and for thorough usage details see the individual verb documentation. TL;DR @@ -79,7 +79,7 @@ contains the current working directory. An important property which deserves attention is the summary value labeled ``Extending``. This describes other collections of libraries and packages which will be visible to your workspace. This is process called "workspace chaining." -The value can be come from a few different sources, and can be classified in +The value can come from a few different sources, and can be classified in one of the three following ways: - No chaining @@ -126,7 +126,7 @@ trivial packages: ``pkg_a``, ``pkg_b``, and ``another_one``: Successfully created files in /tmp/path/to/my_catkin_ws/src/another_one. Please adjust the values in package.xml. After these operations, your workspace's local directory structure would look like -the followng (to two levels deep): +the following (up to two levels deep): .. code-block:: bash @@ -144,12 +144,12 @@ Now that there are some packages in the workspace, Catkin has something to build .. note:: - Catkin utilizes an "out-of-source" and "aggregated" build pattern. This - means that not only will temporary or final build products never be placed - in a package's source directory (or anywhere in the **source space** for - that matter), but also all build directories are aggregated in the **build - space** and all final build products (executables, libraries, etc.) will be - put in the **devel space**. + Catkin utilizes an "out-of-source" and "aggregated" build pattern. This + means that temporary or final build products will never be placed in a + package’s source directory or anywhere in the **source space**. Instead, + all build directories are aggregated in the **build space** and all final + build products like executables, libraries, etc., will be put in the + **devel space**. Building the Workspace ^^^^^^^^^^^^^^^^^^^^^^ @@ -195,7 +195,7 @@ and build each of them. Calling ``catkin build`` will generate ``build`` and ``devel`` directories (as described in the config summary above) and result in a directory structure like -the following (to one level deep): +the following (one level deep): .. code-block:: bash @@ -217,7 +217,7 @@ the build configuration see the :doc:`build verb ` and Loading the Workspace Environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to properly "use" the products of the workspace, it's environment needs +In order to properly "use" the products of the workspace, its environment needs to be loaded. Among other environment variables, sourcing a Catkin setup file modifies the ``CMAKE_PREFIX_PATH`` environment variable, which will affect workspace chaining as described in the earlier section. From 5597566d397285de534c63b3b12bf45802ea9524 Mon Sep 17 00:00:00 2001 From: Jonathan Bohren Date: Tue, 12 Apr 2016 23:42:00 -0400 Subject: [PATCH 06/10] docs: Updating CLI interfaces, re-aligning sentences to lines in paragraphs, fixing some typos --- docs/advanced/job_executor.rst | 155 +++--- docs/advanced/verb_customization.rst | 59 +-- docs/build_types.rst | 11 +- docs/cheat_sheet.rst | 5 +- docs/config_summary.rst | 60 +-- docs/development/adding_build_types.rst | 35 +- docs/examples/failure_ws/1_build_warning.bash | 0 docs/examples/failure_ws/2_build_err.bash | 0 docs/examples/quickstart_ws/2_postbuild.bash | 0 docs/history.rst | 104 ++-- docs/index.rst | 28 +- docs/installing.rst | 12 +- docs/mechanics.rst | 458 +++++++----------- docs/migration.rst | 181 +++---- docs/quick_start.rst | 131 ++--- docs/troubleshooting.rst | 18 +- docs/verbs/catkin_build.rst | 148 ++---- docs/verbs/catkin_clean.rst | 12 +- docs/verbs/catkin_config.rst | 99 ++-- docs/verbs/catkin_env.rst | 8 +- docs/verbs/catkin_init.rst | 18 +- docs/verbs/catkin_list.rst | 15 +- docs/verbs/catkin_locate.rst | 4 +- docs/verbs/catkin_profile.rst | 39 +- docs/verbs/cli/catkin_clean.txt | 63 ++- docs/verbs/cli/catkin_config.txt | 10 +- docs/verbs/cli/catkin_create_pkg.txt | 2 +- docs/verbs/cli/catkin_list.txt | 35 +- docs/verbs/cli/catkin_locate.txt | 3 +- 29 files changed, 665 insertions(+), 1048 deletions(-) mode change 100644 => 100755 docs/examples/failure_ws/1_build_warning.bash mode change 100644 => 100755 docs/examples/failure_ws/2_build_err.bash mode change 100644 => 100755 docs/examples/quickstart_ws/2_postbuild.bash diff --git a/docs/advanced/job_executor.rst b/docs/advanced/job_executor.rst index fe384177..657cf7f3 100644 --- a/docs/advanced/job_executor.rst +++ b/docs/advanced/job_executor.rst @@ -1,33 +1,27 @@ The Catkin Execution Engine =========================== -One of the core modules in ``catkin_tools`` is the **job executor**. The -executor performs jobs required to complete a task in a way that maximizes (or -achives a specific) resource utilization subject to job dependency constraints. -The executor is closely integrated with logging and job output capture. This -page details the design and implementation of the executor. +One of the core modules in ``catkin_tools`` is the **job executor**. +The executor performs jobs required to complete a task in a way that maximizes (or achives a specific) resource utilization subject to job dependency constraints. +The executor is closely integrated with logging and job output capture. +This page details the design and implementation of the executor. Execution Model ^^^^^^^^^^^^^^^ -The execution model is fairly simple. The executor executes a single **task** -for a given command (i.e. ``build``, ``clean``, etc.). A **task** is a set of -**jobs** which are related by an acyclic dependency graph. Each **job** is -given a unique identifier and is composed of a set of dependencies and a -sequence of executable **stages**, which are arbitrary functions or subprocess -calls which utilize one or more **workers** to be executed. The allocation of -workers is managed by the **job server**. Throughout execution, synchronization -with the user-facing interface and output formatting are mediated by a simple -**event queue**. - -The executor is single-threaded and uses an asynchronous loop to execute jobs -as futures. If a job contains blocking stages it can utilize a normal thread -pool for execution, but is still only guaranteed one worker by the main loop of -the executor. See the following section for more information on workers and the -job server. - -The input to the executor is a list of topologically-sorted jobs with no -circular dependencies and some parameters which control the jobserver behavior. +The execution model is fairly simple. +The executor executes a single **task** for a given command (i.e. +``build``, ``clean``, etc.). +A **task** is a set of **jobs** which are related by an acyclic dependency graph. +Each **job** is given a unique identifier and is composed of a set of dependencies and a sequence of executable **stages**, which are arbitrary functions or subprocess calls which utilize one or more **workers** to be executed. +The allocation of workers is managed by the **job server**. +Throughout execution, synchronization with the user-facing interface and output formatting are mediated by a simple **event queue**. + +The executor is single-threaded and uses an asynchronous loop to execute jobs as futures. +If a job contains blocking stages it can utilize a normal thread pool for execution, but is still only guaranteed one worker by the main loop of the executor. +See the following section for more information on workers and the job server. + +The input to the executor is a list of topologically-sorted jobs with no circular dependencies and some parameters which control the jobserver behavior. These behavior parameters are explained in detail in the following section. Each job is in one of the following lifecycle states at any time: @@ -44,42 +38,30 @@ Each job is in one of the following lifecycle states at any time: **Executor Job lifecycle** -All jobs begin in the ``PENDING`` state, and any jobs with unsatisfiable -dependencies are immediately set to ``ABANDONED``, and any jobs without -dependencies are immediately set to ``QUEUED``. After the state initialization, -the executor processes jobs in a main loop until they are in one of the two -terminal states (``FINISHED`` or ``ABANDONED``). - +All jobs begin in the ``PENDING`` state, and any jobs with unsatisfiable dependencies are immediately set to ``ABANDONED``, and any jobs without dependencies are immediately set to ``QUEUED``. +After the state initialization, the executor processes jobs in a main loop until they are in one of the two terminal states (``FINISHED`` or ``ABANDONED``). Each main loop iteration does the following: - - While job server tokens are available, create futures for ``QUEUED`` jobs - and make them ``ACTIVE`` + - While job server tokens are available, create futures for ``QUEUED`` jobs and make them ``ACTIVE`` - Report status of all jobs to the event queue - - Retrieve ``ACTIVE`` job futures which have completed and set them - ``FINISHED`` - - Check for any ``PENDING`` jobs which need to be ``ABANDONED`` due to failed - jobs + - Retrieve ``ACTIVE`` job futures which have completed and set them ``FINISHED`` + - Check for any ``PENDING`` jobs which need to be ``ABANDONED`` due to failed jobs - Change all ``PENDING`` jobs whose dependencies are satisifed to ``QUEUED`` -Once each job is in one of terminal states, the executor pushes a final status -event and returns. - +Once each job is in one of terminal states, the executor pushes a final status event and returns. Job Server Resource Model ^^^^^^^^^^^^^^^^^^^^^^^^^ -As mentioned in the previous section, each task includes a set of jobs which -are activated by the **job server**. In order to start a queued job, at least -one worker needs to be available. Once a job is started, it is assigned a -single worker from the job server. These are considered **top-level jobs** -since they are managed directly by the catkin executor. The number of top-level -jobs can be configured for a given task. - -Additionally to top-level paralellism, some job stages are capable of running -in parallel, themselves. In such cases, the job server can interface directly -with the underlying stage's low-level job allocation. This enables multi-level -parallelism without allocating more than a fixed number of jobs. +As mentioned in the previous section, each task includes a set of jobs which are activated by the **job server**. +In order to start a queued job, at least one worker needs to be available. +Once a job is started, it is assigned a single worker from the job server. +These are considered **top-level jobs** since they are managed directly by the catkin executor. +The number of top-level jobs can be configured for a given task. +Additionally to top-level paralellism, some job stages are capable of running in parallel, themselves. +In such cases, the job server can interface directly with the underlying stage's low-level job allocation. +This enables multi-level parallelism without allocating more than a fixed number of jobs. .. figure:: executor_job_resources.svg :scale: 50 % @@ -87,58 +69,43 @@ parallelism without allocating more than a fixed number of jobs. **Executor Job Flow and Resource Utilization** -- In this snapshot of the job pipeline, the executor is executing four of six possible top-level jobs, each with three stages, and using sevel of eight total workers. Two jobs are executing subprocesses, which have side-channel communication with the job server. -One such parallel-capable stage is the GNU Make build stage. In this case, the -job server implements a GNU Make job server interface, which involves reading -and writing tokens from file handles passed as build flags to the Make command. +One such parallel-capable stage is the GNU Make build stage. +In this case, the job server implements a GNU Make job server interface, which involves reading and writing tokens from file handles passed as build flags to the Make command. -For top-level jobs, additional resources are monitored in addition to the -number of workers. Both system load and memory utilization checks can be -enabled to prevent overloading a system. +For top-level jobs, additional resources are monitored in addition to the number of workers. +Both system load and memory utilization checks can be enabled to prevent overloading a system. Executor Job Failure Behavior ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The executor's behavior when a job fails can be modified with the following two -parameters: - - - ``continue_on_failure`` Continue executing jobs even if one job fails. If - this is set to ``false`` (the default), it will cause the executor to - abandon all pending and queued jobs and stop after the first failure. Note - that active jobs will still be allowed to complete before the executor - returns. - - ``continue_without_deps`` Continue executing jobs even if one - or more of their dependencies have failed. If this is set to ``false`` (the - default), it will cause the executor to abandon only the jobs which depend - on the failed job. If it is set to ``true``, then it will build dependent - jobs regardless. +The executor's behavior when a job fails can be modified with the following two parameters: + - ``continue_on_failure`` Continue executing jobs even if one job fails. + If this is set to ``false`` (the default), it will cause the executor to abandon all pending and queued jobs and stop after the first failure. + Note that active jobs will still be allowed to complete before the executor returns. + - ``continue_without_deps`` Continue executing jobs even if one or more of their dependencies have failed. + If this is set to ``false`` (the default), it will cause the executor to abandon only the jobs which depend on the failed job. + If it is set to ``true``, then it will build dependent jobs regardless. Jobs and Job Stages ^^^^^^^^^^^^^^^^^^^ -As mentioned above, a **job** is a set of dependencies and a sequence of **job -stages**. Jobs and stages are constructed before a given task starts executing, -and hold only specificaitons of what needs to be done to complete them. All -stages are given a label for user introspection, a logger interface, and can -either require or not require allocation of a worker from the job server. +As mentioned above, a **job** is a set of dependencies and a sequence of **job stages**. +Jobs and stages are constructed before a given task starts executing, and hold only specificaitons of what needs to be done to complete them. +All stages are given a label for user introspection, a logger interface, and can either require or not require allocation of a worker from the job server. Stage execution is performed asynchronously by Python's ``asyncio`` module. -This means that exceptions thrown in job stages are handled directly by the -executor. It also means job stages can be interrupted easily through Python's -normal signal handling mechanism. +This means that exceptions thrown in job stages are handled directly by the executor. +It also means job stages can be interrupted easily through Python's normal signal handling mechanism. -Stages can either be **command stages** (subprocess commands) or **function -stages** (python functions). In either case, loggers used by stages support -segmentation of ``stdout`` and ``stderr`` from job stages for both real-time -introspection and logging. +Stages can either be **command stages** (subprocess commands) or **function stages** (python functions). +In either case, loggers used by stages support segmentation of ``stdout`` and ``stderr`` from job stages for both real-time introspection and logging. Command Stages ~~~~~~~~~~~~~~~ -In addition to the basic arguments mentioned above, command stages are -paramterized by the standard subprocess command arguments including the -following: +In addition to the basic arguments mentioned above, command stages are paramterized by the standard subprocess command arguments including the following: - The command, itself, and its arguments, - The working directory for the command, @@ -147,30 +114,24 @@ following: - Whether to emulate a TTY - Whether to partition ``stdout`` and ``stderr`` -When executed, command stages use ``asncio``'s asynchronous process executor -with a custom I/O protocol. +When executed, command stages use ``asncio``'s asynchronous process executor with a custom I/O protocol. Function Stages ~~~~~~~~~~~~~~~ -In addition to the basic arguments mentioned above, function stages are -parameterized by a function handle and a set of function-specific Python -arguments and keyword arguments. When executed, they use the thread pool -mentioned above. +In addition to the basic arguments mentioned above, function stages are parameterized by a function handle and a set of function-specific Python arguments and keyword arguments. +When executed, they use the thread pool mentioned above. Since the function stages aren't subprocesses, I/O isn't piped or redirected. -Instead, a custom I/O logger is passed to the function for output. Functions -used as function stages should use this logger to write to ``stdout`` and -``stderr`` instead of using normal system calls. +Instead, a custom I/O logger is passed to the function for output. +Functions used as function stages should use this logger to write to ``stdout`` and ``stderr`` instead of using normal system calls. Introspection via Executor Events ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Introspection into the different asynchronously-executed components of a task -is performed by a simple event queue. Events are created by the executor, -loggers, and stages, and they are consumed by an output controller. Events are -defined by an event identifier and a data payload, which is an arbitrary -dictionary. +Introspection into the different asynchronously-executed components of a task is performed by a simple event queue. +Events are created by the executor, loggers, and stages, and they are consumed by an output controller. +Events are defined by an event identifier and a data payload, which is an arbitrary dictionary. There are numerous events which correspond to changes in job states, but events are also used for transporting captured I/O from job stages. diff --git a/docs/advanced/verb_customization.rst b/docs/advanced/verb_customization.rst index d3f7b7ee..8e84779a 100644 --- a/docs/advanced/verb_customization.rst +++ b/docs/advanced/verb_customization.rst @@ -1,18 +1,14 @@ Verb Aliasing ============= -The ``catkin`` command allows you to define your own verb "aliases" which -expand to more complex expressions including built-in verbs, command-line -options, and other verb aliases. These are processed before any other -command-line processing takes place, and can be useful for making certain use -patterns more convenient. +The ``catkin`` command allows you to define your own verb "aliases" which expand to more complex expressions including built-in verbs, command-line options, and other verb aliases. +These are processed before any other command-line processing takes place, and can be useful for making certain use patterns more convenient. The Built-In Aliases ^^^^^^^^^^^^^^^^^^^^ -You can list the available aliases using the ``--list-aliases`` option to the -``catkin`` command. Below are the built-in aliases as displayed by this -command: +You can list the available aliases using the ``--list-aliases`` option to the ``catkin`` command. +Below are the built-in aliases as displayed by this command: .. code-block:: bash @@ -26,23 +22,16 @@ command: Defining Additional Aliases ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Verb aliases are defined in the ``verb_aliases`` -subdirectory of the catkin config folder, -``~/.config/catkin/verb_aliases``. Any YAML files in that -folder (files with a ``.yaml`` extension) will be processed as -definition files. +Verb aliases are defined in the ``verb_aliases`` subdirectory of the catkin config folder, ``~/.config/catkin/verb_aliases``. +Any YAML files in that folder (files with a ``.yaml`` extension) will be processed as definition files. -These files are formatted as simple YAML dictionaries which map aliases to -expanded expressions, which must be composed of other ``catkin`` verbs, -options, or aliases: +These files are formatted as simple YAML dictionaries which map aliases to expanded expressions, which must be composed of other ``catkin`` verbs, options, or aliases: .. code-block:: yaml : -For example, aliases which configure a workspace profile so that it ignores the -value of the ``CMAKE_PREFIX_PATH`` environment variable, and instead *extends* -one or another ROS install spaces could be defined as follows: +For example, aliases which configure a workspace profile so that it ignores the value of the ``CMAKE_PREFIX_PATH`` environment variable, and instead *extends* one or another ROS install spaces could be defined as follows: .. code-block:: yaml @@ -50,8 +39,7 @@ one or another ROS install spaces could be defined as follows: extend-sys: config --profile sys --extend /opt/ros/hydro -x _sys extend-overlay: config --profile overlay --extend ~/ros/hydro/install -x _overlay -After defining these aliases, one could use them with optional additional -options and build a given configuration profile. +After defining these aliases, one could use them with optional additional options and build a given configuration profile. .. code-block:: bash @@ -61,23 +49,16 @@ options and build a given configuration profile. .. note:: - The ``catkin`` command will initialize the ``verb_aliases`` directory with a - file named ``00-default-aliases.yaml`` containing the set of built-in - aliases. These defaults can be overridden by adding additional definition - files, but the default alias file should not be modified since any changes to - it will be over-written by invocations of the ``catkin`` command. + The ``catkin`` command will initialize the ``verb_aliases`` directory with a file named ``00-default-aliases.yaml`` containing the set of built-in aliases. + These defaults can be overridden by adding additional definition files, but the default alias file should not be modified since any changes to it will be over-written by invocations of the ``catkin`` command. Alias Precedence and Overriding Aliases ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Verb alias files in the ``verb_aliases`` directory are processed in -alphabetical order, so files which start with larger numbers will override -files with smaller numbers. In this way you can override the built-in -aliases using a file which starts with a number higher than ``00-``. +Verb alias files in the ``verb_aliases`` directory are processed in alphabetical order, so files which start with larger numbers will override files with smaller numbers. +In this way you can override the built-in aliases using a file which starts with a number higher than ``00-``. -For example, the ``bt: build --this`` alias exists in the default alias file, -``00-default-aliases.yaml``, but you can create a file to override it with an -alternate definition defined in a file named ``01-my-aliases.yaml``. +For example, the ``bt: build --this`` alias exists in the default alias file, ``00-default-aliases.yaml``, but you can create a file to override it with an alternate definition defined in a file named ``01-my-aliases.yaml``. .. code-block:: yaml @@ -85,10 +66,8 @@ alternate definition defined in a file named ``01-my-aliases.yaml``. # Override `bt` to build with no deps bt: build --this --no-deps -You can also disable or unset an alias by setting its value to ``null``. For -example, the ``ls: list`` alias is defined in the default aliases, but you can -override it with this entry in a custom file named something like -``02-unset.yaml``: +You can also disable or unset an alias by setting its value to ``null``. +For example, the ``ls: list`` alias is defined in the default aliases, but you can override it with this entry in a custom file named something like ``02-unset.yaml``: .. code-block:: yaml @@ -99,10 +78,8 @@ override it with this entry in a custom file named something like Recursive Alias Expansion ^^^^^^^^^^^^^^^^^^^^^^^^^ -Additionally, verb aliases can be recursive, for instance in the ``bt`` alias, -the ``b`` alias expands to ``build`` so that ``b --this`` expands to ``build ---this``. The ``catkin`` command shows the expansion of aliases when they are -invoked so that their behavior is more transparent: +Additionally, verb aliases can be recursive, for instance in the ``bt`` alias, the ``b`` alias expands to ``build`` so that ``b --this`` expands to ``build --this``. +The ``catkin`` command shows the expansion of aliases when they are invoked so that their behavior is more transparent: .. code-block:: bash diff --git a/docs/build_types.rst b/docs/build_types.rst index 97d1759f..f0fe2915 100644 --- a/docs/build_types.rst +++ b/docs/build_types.rst @@ -6,17 +6,14 @@ The current release of ``catkin_tools`` supports building two types of packages: - **Catkin** -- CMake packages that use the Catkin CMake macros - **CMake** -- "Plain" CMake packages -There is currently limited support for adding other build types. For information -on extending ``catkin_tools`` to be able to build other types of packages, see -:doc:`Adding New Build Types `. Below are -details on the stages involved in building a given package for each of -the currently-supported build types. +There is currently limited support for adding other build types. +For information on extending ``catkin_tools`` to be able to build other types of packages, see :doc:`Adding New Build Types `. +Below are details on the stages involved in building a given package for each of the currently-supported build types. Catkin ^^^^^^ -Catkin packages are CMake packages which utilize the Catkin CMake macros for -finding packages and defining configuration files. +Catkin packages are CMake packages which utilize the Catkin CMake macros for finding packages and defining configuration files. Configuration Arguments ----------------------- diff --git a/docs/cheat_sheet.rst b/docs/cheat_sheet.rst index 54ca3993..1d8461e1 100644 --- a/docs/cheat_sheet.rst +++ b/docs/cheat_sheet.rst @@ -2,9 +2,8 @@ Cheat Sheet =========== This is a non-exhaustive list of some common and useful invocations of the ``catkin`` command. -All of the commands which do not explicitly specify a workspace path (with ``--workspace``) -are assumed to be run from within a directory contained by the target workspace. For thorough -documentation, please see the chapters on each verb. +All of the commands which do not explicitly specify a workspace path (with ``--workspace``) are assumed to be run from within a directory contained by the target workspace. +For thorough documentation, please see the chapters on each verb. Initializing Workspaces ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/config_summary.rst b/docs/config_summary.rst index 2bd6d007..83edc2a1 100644 --- a/docs/config_summary.rst +++ b/docs/config_summary.rst @@ -4,8 +4,7 @@ Configuration Summary Contents of the Config Summary ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Most ``catkin`` commands which modify a workspace's configuration will -display the standard configuration summary, as shown below: +Most ``catkin`` commands which modify a workspace's configuration will display the standard configuration summary, as shown below: .. code-block:: bash @@ -35,11 +34,9 @@ display the standard configuration summary, as shown below: Workspace configuration appears valid. -------------------------------------------------------------- -This summary describes the layout of the workspace as well as other important -settings which influence build and execution behavior. Each of these options -can be modified either with the ``config`` verb's options described in the full -command-line usage or by changing environment variables. The summary is -composed of the following sections: +This summary describes the layout of the workspace as well as other important settings which influence build and execution behavior. +Each of these options can be modified either with the ``config`` verb's options described in the full command-line usage or by changing environment variables. +The summary is composed of the following sections: Overview Section ---------------- @@ -96,23 +93,17 @@ what is wrong and how you can fix it. Workspace Chaining Mode ^^^^^^^^^^^^^^^^^^^^^^^ -An important property listed in the configuration configuration which deserves -attention is the summary value of the ``Extending`` property. This affects -which other collections of libraries and packages which will be visible to your -workspace. This is process called "workspace chaining." For more details on this -see the details about workspace chaining and ``CMAKE_PREFIX_PATH`` in -:doc:`Workspace Mechanics `. +An important property listed in the configuration configuration which deserves attention is the summary value of the ``Extending`` property. +This affects which other collections of libraries and packages which will be visible to your workspace. +This is process called "workspace chaining." For more details on this see the details about workspace chaining and ``CMAKE_PREFIX_PATH`` in :doc:`Workspace Mechanics `. -The information about which workspace to extend can come from a few different -sources, and can be classified in one of three ways: +The information about which workspace to extend can come from a few different sources, and can be classified in one of three ways: No Chaining ----------- -This is what is shown in the above example configuration and it implies that -there are no other Catkin workspaces which this workspace extends. The user has -neither explicitly specified a workspace to extend, and the -``CMAKE_PREFIX_PATH`` environment variable is empty: +This is what is shown in the above example configuration and it implies that there are no other Catkin workspaces which this workspace extends. +The user has neither explicitly specified a workspace to extend, and the ``CMAKE_PREFIX_PATH`` environment variable is empty: .. code-block:: bash @@ -121,43 +112,32 @@ neither explicitly specified a workspace to extend, and the Implicit Chaining via ``CMAKE_PREFIX_PATH`` Environment or Cache Variable ------------------------------------------------------------------------- -In this case, the ``catkin`` command is *implicitly* assuming that you want -to build this workspace against resources which have been built into the -directories listed in your ``CMAKE_PREFIX_PATH`` environment variable. As -such, you can control this value simply by changing this environment -variable. +In this case, the ``catkin`` command is *implicitly* assuming that you want to build this workspace against resources which have been built into the directories listed in your ``CMAKE_PREFIX_PATH`` environment variable. +As such, you can control this value simply by changing this environment variable. -For example, ROS users who load their system's installed ROS environment by -calling something similar to ``source /opt/ros/hydro/setup.bash`` will -normally see an ``Extending`` value such as: +For example, ROS users who load their system's installed ROS environment by calling something similar to ``source /opt/ros/hydro/setup.bash`` will normally see an ``Extending`` value such as: .. code-block:: bash Extending: [env] /opt/ros/hydro -If you don't want to extend the given workspace, unsetting the -``CMAKE_PREFIX_PATH`` environment variable will change it back to none. You can -also alternatively +If you don't want to extend the given workspace, unsetting the ``CMAKE_PREFIX_PATH`` environment variable will change it back to none. -Once you have built your workspace once, this ``CMAKE_PREFIX_PATH`` will be -cached by the underlying CMake buildsystem. As such, the ``Extending`` status -will subsequently describe this as the "cached" extension path: +Once you have built your workspace once, this ``CMAKE_PREFIX_PATH`` will be cached by the underlying CMake buildsystem. +As such, the ``Extending`` status will subsequently describe this as the "cached" extension path: .. code-block:: bash Extending: [cached] /opt/ros/hydro -Once the extension mode is cached like this, you must use ``catkin clean`` to -before changing it to something else. +Once the extension mode is cached like this, you must use ``catkin clean`` to before changing it to something else. Explicit Chaining via ``catkin config --extend`` ------------------------------------------------ -This behaves like the above implicit chaining except it means that this -workspace is *explicitly* extending another workspace and the workspaces -which the other workspace extends, recursively. This can be set with the -``catkin config --extend`` command. It will override the value of -``CMAKE_PREFIX_PATH`` and persist between builds. +This behaves like the above implicit chaining except it means that this workspace is *explicitly* extending another workspace and the workspaces which the other workspace extends, recursively. +This can be set with the ``catkin config --extend`` command. +It will override the value of ``CMAKE_PREFIX_PATH`` and persist between builds. .. code-block:: bash diff --git a/docs/development/adding_build_types.rst b/docs/development/adding_build_types.rst index 5d0b8bcd..bbfd408f 100644 --- a/docs/development/adding_build_types.rst +++ b/docs/development/adding_build_types.rst @@ -6,15 +6,11 @@ The current release of ``catkin_tools`` supports building two types of packages: - **Catkin** -- CMake packages that use the Catkin CMake macros - **CMake** -- "Plain" CMake packages -In order to fully support additional build types, numerous additions need to be -made to the command-line interfaces so that the necessary parameters can be passed -to the ``build`` verb. For partial support, however, all that's needded is to -add a build type identifier and a function for generating build jobs. +In order to fully support additional build types, numerous additions need to be made to the command-line interfaces so that the necessary parameters can be passed to the ``build`` verb. +For partial support, however, all that's needded is to add a build type identifier and a function for generating build jobs. -The supported build typs are easily extendable using the ``setuptools`` -``entry_points`` interface without modifying the ``catkin_tools`` project, -itself. Regardless of what package the ``entry_point`` is defined in, it will -be defined in the ``setup.py`` of that package, and will take this form: +The supported build typs are easily extendable using the ``setuptools`` ``entry_points`` interface without modifying the ``catkin_tools`` project, itself. +Regardless of what package the ``entry_point`` is defined in, it will be defined in the ``setup.py`` of that package, and will take this form: .. code-block:: python @@ -30,15 +26,12 @@ be defined in the ``setup.py`` of that package, and will take this form: }, ) -This entry in the ``setup.py`` places a file in the ``PYTHONPATH`` when either -the ``install`` or the ``develop`` verb is given to ``setup.py``. This file -relates the key (in this case ``mybuild``) to a module and attribute (in this -case ``my_package.some.module`` and ``description``). +This entry in the ``setup.py`` places a file in the ``PYTHONPATH`` when either the ``install`` or the ``develop`` verb is given to ``setup.py``. +This file relates the key (in this case ``mybuild``) to a module and attribute (in this case ``my_package.some.module`` and ``description``). -Then the ``catkin`` command will use the ``pkg_resources`` modules to retrieve -these mapping at run time. Any entry for the ``catkin_tools.jobs`` group must -point to a ``description`` attribute of a module, where the ``description`` -attribute is a ``dict``. The ``description`` ``dict`` should take this form: +Then the ``catkin`` command will use the ``pkg_resources`` modules to retrieve these mapping at run time. +Any entry for the ``catkin_tools.jobs`` group must point to a ``description`` attribute of a module, where the ``description`` attribute is a ``dict``. +The ``description`` ``dict`` should take this form: .. code-block:: python @@ -48,12 +41,10 @@ attribute is a ``dict``. The ``description`` ``dict`` should take this form: create_build_job=create_mybuild_build_job ) -This ``dict`` defines all the information that the ``catkin`` command needs to -create jobs for the ``mybuild`` build type. The ``build_type`` key takes a -string which is the build type identifier. The ``description`` key takes a -string which briefly describes the build type. The ``create_build_job`` key -takes a callable (function) factory which is called in order to create a -``Job`` to build a package of type ``mybuild``. +This ``dict`` defines all the information that the ``catkin`` command needs to create jobs for the ``mybuild`` build type. +The ``build_type`` key takes a string which is the build type identifier. +The ``description`` key takes a string which briefly describes the build type. +The ``create_build_job`` key takes a callable (function) factory which is called in order to create a ``Job`` to build a package of type ``mybuild``. The signature of the factory callable should be similar to the following: diff --git a/docs/examples/failure_ws/1_build_warning.bash b/docs/examples/failure_ws/1_build_warning.bash old mode 100644 new mode 100755 diff --git a/docs/examples/failure_ws/2_build_err.bash b/docs/examples/failure_ws/2_build_err.bash old mode 100644 new mode 100755 diff --git a/docs/examples/quickstart_ws/2_postbuild.bash b/docs/examples/quickstart_ws/2_postbuild.bash old mode 100644 new mode 100755 diff --git a/docs/history.rst b/docs/history.rst index 4b5eab61..68ad0d82 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -5,24 +5,14 @@ A Brief History of Catkin Legacy Catkin Workflow ^^^^^^^^^^^^^^^^^^^^^^ -The core Catkin meta-buildsystem was originally designed in order to -efficiently build numerous inter-dependent, but separately developed, CMake -projects. This was developed by the Robot Operating System (ROS) -community, originally as a successor to the standard meta-buildtool -``rosbuild``. The ROS community's distributed development model with many -modular projects and the need for building distributable binary packages -motivated the design of a system which efficiently merged numerous disparate -projects so that they utilize a single target dependency tree and build space. - -To facilitate this "merged" build process, a workspace's **source space** -would contain boiler-plate "top-level" ``CMakeLists.txt`` which automatically -added all of the Catkin CMake projects below it to the single large CMake -project. - -Then the user would build this collection of projects like a single unified -CMake project with a workflow similar to the standard CMake out-of-source build -workflow. They would all be configured with one invocation of ``cmake`` and -subsequently targets would be built with one or more invocations of ``make``: +The core Catkin meta-buildsystem was originally designed in order to efficiently build numerous inter-dependent, but separately developed, CMake projects. +This was developed by the Robot Operating System (ROS) community, originally as a successor to the standard meta-buildtool ``rosbuild``. +The ROS community's distributed development model with many modular projects and the need for building distributable binary packages motivated the design of a system which efficiently merged numerous disparate projects so that they utilize a single target dependency tree and build space. + +To facilitate this "merged" build process, a workspace's **source space** would contain boiler-plate "top-level" ``CMakeLists.txt`` which automatically added all of the Catkin CMake projects below it to the single large CMake project. + +Then the user would build this collection of projects like a single unified CMake project with a workflow similar to the standard CMake out-of-source build workflow. +They would all be configured with one invocation of ``cmake`` and subsequently targets would be built with one or more invocations of ``make``: .. code-block:: bash @@ -31,10 +21,8 @@ subsequently targets would be built with one or more invocations of ``make``: $ cmake ../src $ make -In order to help automate the merged build process, Catkin was distributed -with a command-line tool called ``catkin_make``. -This command automated the above CMake work flow while setting some -variables according to standard conventions. +In order to help automate the merged build process, Catkin was distributed with a command-line tool called ``catkin_make``. +This command automated the above CMake work flow while setting some variables according to standard conventions. These defaults would result in the execution of the following commands: .. code-block:: bash @@ -44,43 +32,28 @@ These defaults would result in the execution of the following commands: $ cmake ../src -DCATKIN_DEVEL_SPACE=../devel -DCMAKE_INSTALL_PREFIX=../install $ make -j -l [optional target, e.g. install] -An advantage of this approach is that the total configuration would be smaller -than configuring each package individually and that the Make targets can be -parallelized even amongst dependent packages. +An advantage of this approach is that the total configuration would be smaller than configuring each package individually and that the Make targets can be parallelized even amongst dependent packages. -In practice, however, it also means that in large workspaces, modification of the -CMakeLists.txt of one package would necessitate the reconfiguration of all packages -in the entire workspace. +In practice, however, it also means that in large workspaces, modification of the CMakeLists.txt of one package would necessitate the reconfiguration of all packages in the entire workspace. A critical flaw of this approach, however, is that there is no fault isolation. -An error in a leaf package (package with no dependencies) will prevent all -packages from configuring. Packages might have colliding target names. The -merged build process can even cause CMake errors to go undetected if one package -defines variables needed by another one, and can depend on the order in which -independent packages are built. Since packages are merged into a single CMake -invocation, this approach also requires developers to specify explicit -dependencies on some targets inside of their dependencies. - -Another disadvantage of the merged build process is that it can only work on a -homogeneous workspace consisting only of Catkin CMake packages. -Other types of packages like plain CMake packages and autotools packages cannot -be integrated into a single configuration and a single build step. +An error in a leaf package (package with no dependencies) will prevent all packages from configuring. +Packages might have colliding target names. +The merged build process can even cause CMake errors to go undetected if one package defines variables needed by another one, and can depend on the order in which independent packages are built. +Since packages are merged into a single CMake invocation, this approach also requires developers to specify explicit dependencies on some targets inside of their dependencies. + +Another disadvantage of the merged build process is that it can only work on a homogeneous workspace consisting only of Catkin CMake packages. +Other types of packages like plain CMake packages and autotools packages cannot be integrated into a single configuration and a single build step. Isolated Catkin Workflow ^^^^^^^^^^^^^^^^^^^^^^^^ -The numerous drawbacks of the merged build process and the ``catkin_make`` tool -motivated the development of the ``catkin_make_isolated`` tool. -In contrast to ``catkin_make``, the ``catkin_make_isolated`` command uses an -isolated build process, wherein each package is independently configured, -built, and loaded into the environment. +The numerous drawbacks of the merged build process and the ``catkin_make`` tool motivated the development of the ``catkin_make_isolated`` tool. +In contrast to ``catkin_make``, the ``catkin_make_isolated`` command uses an isolated build process, wherein each package is independently configured, built, and loaded into the environment. -This way, each package is built in isolation and the next packages are built on -the atomic result of the current one. This resolves the issues with target -collisions, target dependency management, and other undesirable cross-talk -between projects. -This also allows for the homogeneous automation of other buildtools like the -plain CMake or autotools. +This way, each package is built in isolation and the next packages are built on the atomic result of the current one. +This resolves the issues with target collisions, target dependency management, and other undesirable cross-talk between projects. +This also allows for the homogeneous automation of other buildtools like the plain CMake or autotools. The isolated workflow also enabled the following features: @@ -88,33 +61,24 @@ The isolated workflow also enabled the following features: - Building Catkin and non-Catkin projects into a single **devel space** - Building packages without re-configuring or re-building their dependencies - Removing the requirement that all packages in the workspace are free - of CMake errors before any packages can be built + of CMake errors before any packages can be built -There are, however, still some problems with ``catkin_make_isolated``. First, -it is dramatically slower than ``catkin_make`` since it cannot parallelize the -building of targets or even packages which do not depend on each other. -It also lacks robustness to changes in the list of packages in the -workspace. Since it is a "released" tool, it also has strict API stability -requirements. +There are, however, still some problems with ``catkin_make_isolated``. +First, it is dramatically slower than ``catkin_make`` since it cannot parallelize the building of targets or even packages which do not depend on each other. +It also lacks robustness to changes in the list of packages in the workspace. +Since it is a "released" tool, it also has strict API stability requirements. Parallel Isolated Catkin Workflow and ``catkin build`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The limitations of ``catkin_make_isolated`` and the need for additional -high-level build tools lead to the development of a parallel version of -catkin make isolated, or ``pcmi``, as part of `Project -Tango `_. -``pcmi`` later became the ``build`` verb of the ``catkin`` command included -in this project. +The limitations of ``catkin_make_isolated`` and the need for additional high-level build tools lead to the development of a parallel version of catkin make isolated, or ``pcmi``, as part of `Project Tango `_. +``pcmi`` later became the ``build`` verb of the ``catkin`` command included in this project. -As such, the principle behavior of the ``build`` verb is to build each -package in isolation and in topological order while parallelizing the -building of packages which do not depend on each other. +As such, the principle behavior of the ``build`` verb is to build each package in isolation and in topological order while parallelizing the building of packages which do not depend on each other. -Other functional improvements over ``catkin_make`` and ``catkin_make_isolated`` -include the following: +Other functional improvements over ``catkin_make`` and ``catkin_make_isolated`` include the following: -- The use of sub-command "verbs" for better organization of build options and +- The use of sub-command "verbs" for better organization of build options and build-related functions - Robustly adapting a build when packages are added to or removed from the **source space** diff --git a/docs/index.rst b/docs/index.rst index 0129dc4c..e97368c8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -56,10 +56,9 @@ Catkin Command Line Tools development/adding_build_types Adding New Verbs -This Python package provides command line tools for working with the catkin -meta-buildsystem and catkin workspaces. These tools are separate from the -Catkin CMake macros used in Catkin source packages. For documentation on -creating catkin packages, see: http://docs.ros.org/api/catkin/html/ +This Python package provides command line tools for working with the catkin meta-buildsystem and catkin workspaces. +These tools are separate from the Catkin CMake macros used in Catkin source packages. +For documentation on creating catkin packages, see: http://docs.ros.org/api/catkin/html/ .. note:: @@ -78,23 +77,18 @@ The ``catkin`` Command .. .. -The ``catkin`` Command-Line Interface (CLI) tool is the single point of entry -for most of the functionality provided by this package. -All invocations of the ``catkin`` CLI tool take this form: +The ``catkin`` Command-Line Interface (CLI) tool is the single point of entry for most of the functionality provided by this package. +All invocations of the ``catkin`` CLI tool take this form: .. code-block:: bash $ catkin [global options] [verb arguments and options] -The different capabilities of the ``catkin`` CLI tool are organized into -different sub-command "verbs." This is similar to common command-line tools -such as ``git`` or ``apt-get``. Verbs include actions such as ``build`` which -builds a catkin workspace or ``list`` which simply lists the catkin packages -found in one or more folders. +The different capabilities of the ``catkin`` CLI tool are organized into different sub-command "verbs." This is similar to common command-line tools such as ``git`` or ``apt-get``. +Verbs include actions such as ``build`` which builds a catkin workspace or ``list`` which simply lists the catkin packages found in one or more folders. -Verbs can take arbitrary arguments and options, but they must all come -after the verb. For more help on the usage of a particular verb, simply pass -the ``-h`` or ``--help`` option after the verb. +Verbs can take arbitrary arguments and options, but they must all come after the verb. +For more help on the usage of a particular verb, simply pass the ``-h`` or ``--help`` option after the verb. Built-in ``catkin`` Verbs ------------------------- @@ -122,9 +116,7 @@ Shell Support for the ``catkin`` Command If you are using ``bash`` or ``zsh``, then you can source an extra setup file to gain access to some additional verbs. For more information see: :doc:`advanced/catkin_shell_verbs`. - Extending the ``catkin`` command -------------------------------- -If you would like to add a verb to the ``catkin`` command without modifying its -source, please read :doc:`Adding New Verbs `. +If you would like to add a verb to the ``catkin`` command without modifying its source, please read :doc:`Adding New Verbs `. diff --git a/docs/installing.rst b/docs/installing.rst index 2114f549..409a2170 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -51,23 +51,21 @@ Then install with the ``setup.py`` file: $ python setup.py install -Note: Depending on your environment/machine, you may need to use ``sudo`` with this command. +.. note:: + + Depending on your environment/machine, you may need to use ``sudo`` with this command. Developing ---------- -Listed here are some useful tips for developing against ``catkin_tools``. - -Install ``catkin_tools`` for developing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - To setup ``catkin_tools`` for fast iteration during development, use the ``develop`` verb to ``setup.py``: .. code-block:: bash $ python setup.py develop -Now the commands, like ``catkin``, will be in the system path and the local source files located in the ``catkin_tools`` folder will be on the ``PYTHONPATH``. When you are done with your development, undo this by running this command: +Now the commands, like ``catkin``, will be in the system path and the local source files located in the ``catkin_tools`` folder will be on the ``PYTHONPATH``. +When you are done with your development, undo this by running this command: .. code-block:: bash diff --git a/docs/mechanics.rst b/docs/mechanics.rst index 27961938..78ddcbef 100644 --- a/docs/mechanics.rst +++ b/docs/mechanics.rst @@ -1,25 +1,112 @@ Workspace Mechanics =================== -This chapter defines the organization, composition, and use of Catkin -workspaces. Catkin workspaces enable rapid simulatnous building and -executing of numerous interdependent projects. These projects do not need to -share the sme buildtool, but they do need to be able to either build or install -to a FHS tree. - -Unlike integrated development -environments (IDEs) which normally only manage single projects, the purpose of -Catkin is to enable the simultaneous compilation of numerous -independently-authored projects. - -Anatomy of a Catkin Workspace -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A standard catkin workspace, as defined by `REP-0128 -`_, is a directory with a prescribed set -of "spaces", each of which is contained within a directory under the workspace -root. The spaces that comprise the workspace are described in the following -sections. +This chapter defines the organization, composition, and use of Catkin workspaces. +Catkin workspaces enable rapid simulatnous building and executing of numerous interdependent projects. +These projects do not need to share the sme buildtool, but they do need to be able to either build or install to a FHS tree. + +Unlike integrated development environments (IDEs) which normally only manage single projects, the purpose of Catkin is to enable the simultaneous compilation of numerous independently-authored projects. + +Workspace Configuration +^^^^^^^^^^^^^^^^^^^^^^^ + +Most ``catkin`` commands which modify a workspace's configuration will +display the standard configuration summary, as shown below: + +.. code-block:: bash + + $ cd /tmp/path/to/my_catkin_ws + $ catkin config + -------------------------------------------------------------- + Profile: default + Extending: None + Workspace: /tmp/path/to/my_catkin_ws + Source Space: [exists] /tmp/path/to/my_catkin_ws/src + Build Space: [missing] /tmp/path/to/my_catkin_ws/build + Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel + Install Space: [missing] /tmp/path/to/my_catkin_ws/install + DESTDIR: None + -------------------------------------------------------------- + Devel Space Layout: merged + Install Packages: False + Isolate Installs: False + -------------------------------------------------------------- + Additional CMake Args: None + Additional Make Args: None + Additional catkin Make Args: None + Internal Make Job Server: True + Cache Job Environments: False + -------------------------------------------------------------- + Whitelisted Packages: None + Blacklisted Packages: None + -------------------------------------------------------------- + Workspace configuration appears valid. + -------------------------------------------------------------- + +This summary describes the layout of the workspace as well as other important settings which influence build and execution behavior. +Each of these options can be modified either with the ``config`` verb's options described in the full command-line usage or by changing environment variables. +The summary is composed of the following sections: + +Overview Section +---------------- + +- **Profile** -- The name of this configuration. +- **Extending** -- Describes if your current configuration will extend another Catkin workspace, and through which mechanism it determined the location of the extended workspace: + + - *No Chaining* + - *Implicit Chaining* -- Derived from the ``CMAKE_PREFIX_PATH`` environment variable. + - *Cached Implicit Chaining* -- Derived from the ``CMAKE_PREFIX_PATH`` CMake cache variable. + - *Explicit Chaining* -- Specified by ``catkin config --extend`` + +- **Workspace** -- The path to the workspace. +- **Source Space** -- The subdirectory containing the source packages. +- **Build Space** -- The subdirectory containing the intermediate build products for each package. +- **Devel Space** -- The subdirectory containing the final build products which can be used to run code, but relies on the presence of the source space. +- **Install Space** -- The subdirectory containing the final build products which can be used to run code, but is entirely self-contained. +- **DESTDIR** -- An optional prefix to the **install space** as defined by `GNU Standards `_ + +Build Product Layout Section +---------------------------- + +- **Devel Space Layout** -- The organization of the **devel space**. + + - *Merged* -- Write products from all packages to a single FHS tree. This is most similar to the behavior of ``catkin_make``. + - *Isolated* -- Write products from each package into independent isolated FHS trees. this is most similar to the behavior of ``catkin_make_isolated``. + - *Linked* -- Write products from each package into independent isolated FHS trees, and symbolically link them into a merged FHS tree. + +- **Install Packages** -- Enable creating and installation into the **install space**. +- **Isolate Installs** -- Installs products into individual FHS subdirectories in the **install space**. + +Build Tool Arguments Section +---------------------------- + +- **Additional CMake Args** -- Arguments to be passed to CMake during the *configuration* step for all packages to be built. +- **Additional Make Args** -- Arguments to be passed to Make during the *build* step for all packages to be built. +- **Additional catkin Make Args** -- Similar to **Additional Make Args** but only applies to Catkin packages. +- **Internal Make Job Server** -- Whether or not the internal job server should be used to coordinate parallel build jobs. +- **Cache Job Environments** -- Whether or not environment variables should be cached between build jobs. + +Package Filter Section +---------------------- + +- **Package Whitelist** -- Packages that will be built with a bare call to ``catkin build``. +- **Package Blacklist** -- Packages that will *not* be built unless explicitly named. + +Notes Section +------------- + +The summary will sometimes contain notes about the workspace or the action that you're performing, or simply tell you that the workspace configuration appears valid. + +Warnings Section +---------------- + +If something is wrong with your configuration such as a missing source space, an additional section will appear at the bottom of the summary with details on what is wrong and how you can fix it. + +Workspace Anatomy +^^^^^^^^^^^^^^^^^ + +A standard catkin workspace, as defined by `REP-0128 `_, is a directory with a prescribed set of "spaces", each of which is contained within a directory under the workspace root. +The spaces that comprise the workspace are described in the following sections. =============== =============== ====================================================== Space Default Path Contents @@ -30,84 +117,64 @@ sections. Install Space ``./install`` FHS tree containing products of ``install`` targets. =============== =============== ====================================================== -In addition to these user-facing directories, ``catkin_tools`` also creates a -hidden ``.catkin_tools`` directory, which stores persistent build -configuration. +In addition to these user-facing directories, ``catkin_tools`` also creates a hidden ``.catkin_tools`` directory, which stores persistent build configuration. source space ------------ -The **source space** contains all of the source packages to be built in the -workspace, as such, it is the only directory required to build a workspace. The -**source space** is also the only directory in the catkin workspace which is not -modified by any ``catkin`` command verb. No build products are written to the -source space, they are all built "out-of-source" in the **build space**, -described in the next section. +The **source space** contains all of the source packages to be built in the workspace, as such, it is the only directory required to build a workspace. +The **source space** is also the only directory in the catkin workspace which is not modified by any ``catkin`` command verb. +No build products are written to the source space, they are all built "out-of-source" in the **build space**, described in the next section. build space ----------- -Intermediate build products are written in the **build space**. The **build -space** contains an isolated build directory for each package, as well as -the log files which capture the output from each build stage. It is from these -directories where commands like ``cmake`` and ``make`` are run. +Intermediate build products are written in the **build space**. +The **build space** contains an isolated build directory for each package, as well as the log files which capture the output from each build stage. +It is from these directories where commands like ``cmake`` and ``make`` are run. devel space ----------- -Build products like executables, libraries, pkg-config files, and CMake config -files, are generated in the **devel space**. The **devel space** is organized -as an `FHS `_ -tree. +Build products like executables, libraries, pkg-config files, and CMake config files, are generated in the **devel space**. +The **devel space** is organized as an `FHS `_ tree. -Some buildtools simply treat the **devel space** as an install prefix, but other -buildtools like ``catkin``, itself, can build targets directly into the **devel -space** in order to skip the additional install step. For such packages, executing -programs from the develspace sometimes requires that the source space is still -available. +Some buildtools simply treat the **devel space** as an install prefix, but other buildtools like ``catkin``, itself, can build targets directly into the **devel space** in order to skip the additional install step. +For such packages, executing programs from the develspace sometimes requires that the source space is still available. -At the root of the **devel space** is a set of environment setup files which can -be "sourced" in order to properly execute the space's products. +At the root of the **devel space** is a set of environment setup files which can be "sourced" in order to properly execute the space's products. install space ------------- -Finally, if the workspace is configured to install packages, the each will be -installed into the **install space**. The **install space** has an FHS layout -like the **devel space**, except it is entirely self-contained. +Finally, if the workspace is configured to install packages, the each will be installed into the **install space**. +The **install space** has an FHS layout like the **devel space**, except it is entirely self-contained. Additional Files Generated by ``catkin_tools`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------------------- Configuration Directory ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ -In addition to the standard workspace structure, ``catkin_tools`` also adds a -marker directory called ``.catkin_tools`` at the root of the workspace. This -directory both acts as a marker for the root of the workspace and contains -persistent configuration information. +In addition to the standard workspace structure, ``catkin_tools`` also adds a marker directory called ``.catkin_tools`` at the root of the workspace. +This directory both acts as a marker for the root of the workspace and contains persistent configuration information. -This directory contains subdirectories representing different configuration -profiles, and inside of each profile directory are YAML files which contain -verb-specific metadata. It additionally contains a file which lists the name of -the active configuration profile if it is different than ``default``. +This directory contains subdirectories representing different configuration profiles, and inside of each profile directory are YAML files which contain verb-specific metadata. +It additionally contains a file which lists the name of the active configuration profile if it is different from ``default``. Build Log Directory -------------------- +~~~~~~~~~~~~~~~~~~~ -The ``catkin`` command also generates a log directory called ``_logs`` in the -**build space** and contains individual build logs for each package. Logs for -each package are written in subdirectories with the same name as the package. +The ``catkin`` command also generates a log directory called ``_logs`` in the **build space** and contains individual build logs for each package. +Logs for each package are written in subdirectories with the same name as the package. -The latest log for each verb and stage in a given package's log directory is -also written with the format: +The latest log for each verb and stage in a given package's log directory is also written with the format: .. code-block:: bash {VERB}.{STAGE}.log -Each previous logfile has the following format, where ``{INDEX}`` begins at -``000`` and increases with each execution of that verb and stage: +Each previous logfile has the following format, where ``{INDEX}`` begins at ``000`` and increases with each execution of that verb and stage: .. code-block:: bash @@ -115,15 +182,12 @@ Each previous logfile has the following format, where ``{INDEX}`` begins at Environment Setup Files -^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ -The FHS trees of the **devel space** and **install space** also contain several -environemnt "setup" scripts. These setup scripts are intended to make it easier -to use the resulting FHS tree for building other source code or for running -programs built by the packages in the workspace. +The FHS trees of the **devel space** and **install space** also contain several environemnt "setup" scripts. +These setup scripts are intended to make it easier to use the resulting FHS tree for building other source code or for running programs built by the packages in the workspace. -The setup script can be used -like this in ``bash``: +The setup script can be used like this in ``bash``: .. code-block:: bash @@ -135,9 +199,7 @@ Or like this in ``zsh``: % source /path/to/workspace/devel/setup.zsh -Sourcing these setup scripts adds this workspace and any "underlaid" workspaces -to your environment, prefixing several environment variables with the -appropriate local workspace folders. +Sourcing these setup scripts adds this workspace and any "underlaid" workspaces to your environment, prefixing several environment variables with the appropriate local workspace folders. ============================= ================================================== Environment Variable | Description @@ -155,7 +217,7 @@ appropriate local workspace folders. ----------------------------- -------------------------------------------------- PKG_CONFIG_PATH_ | Search path for ``pkg-config`` files. ----------------------------- -------------------------------------------------- - PYTHONPATH_ | Search path for Python modules. + PYTHONPATH_ | Search path for Python modules. ============================= ================================================== .. _CMAKE_PREFIX_PATH: https://cmake.org/cmake/help/v3.0/variable/CMAKE_PREFIX_PATH.html @@ -190,205 +252,61 @@ Source Packages and Dependencies A package is any folder which contains a ``package.xml`` as defined by the ROS community in ROS Enhancement Proposals -`REP-0127 `_ +`REP-0127 `_ and `REP-0140 `_. -The ``catkin build`` command builds packages in the topological order -determined by the dependencies listed in the package's ``package.xml`` file. -For more information on which dependencies contribute to the build order, see -the :doc:`build verb documentation`. - -Additionally, the ``build_type`` tag is used to determine which build stages to -use on the package. Supported build types are listed in :doc:`Build Types -`. Packages without a ``build_type`` tag are assumed to be catkin -packages. - -For example, plain CMake packages can be built by adding a ``package.xml`` file -to the root of their source tree with the ``build_type`` flag set to ``cmake`` -and appropriate ``build_depend`` and ``run_depend`` tags set, as described in -`REP-0136 `_. This can been done to -build packages like ``opencv``, ``pcl``, and ``flann``. - -Workspace Configuration -^^^^^^^^^^^^^^^^^^^^^^^ - -Most ``catkin`` commands which modify a workspace's configuration will -display the standard configuration summary, as shown below: - -.. code-block:: bash - - $ cd /tmp/path/to/my_catkin_ws - $ catkin config - -------------------------------------------------------------- - Profile: default - Extending: None - Workspace: /tmp/path/to/my_catkin_ws - Source Space: [exists] /tmp/path/to/my_catkin_ws/src - Build Space: [missing] /tmp/path/to/my_catkin_ws/build - Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel - Install Space: [missing] /tmp/path/to/my_catkin_ws/install - DESTDIR: None - -------------------------------------------------------------- - Devel Space Layout: merged - Install Packages: False - Isolate Installs: False - -------------------------------------------------------------- - Additional CMake Args: None - Additional Make Args: None - Additional catkin Make Args: None - Internal Make Job Server: True - Cache Job Environments: False - -------------------------------------------------------------- - Whitelisted Packages: None - Blacklisted Packages: None - -------------------------------------------------------------- - Workspace configuration appears valid. - -------------------------------------------------------------- - -This summary describes the layout of the workspace as well as other important -settings which influence build and execution behavior. Each of these options -can be modified either with the ``config`` verb's options described in the full -command-line usage or by changing environment variables. The summary is -composed of the following sections: - -Overview Section ----------------- - -- **Profile** -- The name of this configuration. -- **Extending** -- Describes if your current configuration will extend another Catkin workspace, and through which mechanism it determined the location of the extended workspace: - - - *No Chaining* - - .. code-block:: bash - - Extending: None - - - *Implicit Chaining* -- Derived from the ``CMAKE_PREFIX_PATH`` environment or cache variable. +The ``catkin build`` command builds packages in the topological order determined by the dependencies listed in the package's ``package.xml`` file. +For more information on which dependencies contribute to the build order, see the :doc:`build verb documentation`. - .. code-block:: bash +Additionally, the ``build_type`` tag is used to determine which build stages to use on the package. +Supported build types are listed in :doc:`Build Types `. +Packages without a ``build_type`` tag are assumed to be catkin packages. - Extending: [env] /opt/ros/hydro - - .. code-block:: bash -. - Extending: [cached] /opt/ros/hydro - - - *Explicit Chaining* -- Specified by ``catkin config --extend`` - - .. code-block:: bash - - Extending: [explicit] /opt/ros/hydro - -- **[* Space]** -- Lists the paths to each of the catkin "spaces" and whether or not they exist -- **DESTDIR** -- An optional prefix to the **install space** as defined by `GNU Standards `_ - -Build Product Layout Section ----------------------------- - -- **Devel Space Layout** -- The organization of the **devel space**. - - - *Merged* -- Write products from all packages to a single FHS tree. This is most similar to the behavior of ``catkin_make``. - - *Isolated* -- Write products from each package into independent isolated FHS trees. this is most similar to the behavior of ``catkin_make_isolated``. - - *Linked* -- Write products from each package into independent isolated FHS trees, and symbolically link them into a merged FHS tree. - -- **Install Packages** -- Enable creating and installation into the **install space** -- **Isolate Installs** -- Installs products into individual FHS subdirectories in the **install space** - -Build Tool Arguments Section ----------------------------- - -- **Additional CMake Args** -- Arguments to be passed to CMake during the *configuration* step for all packages to be built. -- **Additional Make Args** -- Arguments to be passed to Make during the *build* step for all packages to be built. -- **Additional catkin Make Args** -- Similar to **Additional Make Args** but only applies to Catkin packages. -- **Internal Make Job Server** -- Whether or not the internal job server should be used to coordinate parallel build jobs. -- **Cache Job Environments** -- Whether or not environment variables should be cached between build jobs. - -Package Filter Section ----------------------- - -- **Package Whitelist** -- Packages that will be built with a bare call to ``catkin build``. -- **Package Blacklist** -- Packages that will *not* be built unless explicitly named. - -Notes Section -------------- - -The summary will sometimes contain notes about the workspace or the action that -you're performing, or simply tell you that the workspace configuration appears -valid. - -Warnings Section ----------------- - -If something is wrong with your configuration such as a missing source space, -an additional section will appear at the bottom of the summary with details on -what is wrong and how you can fix it. +For example, plain CMake packages can be built by adding a ``package.xml`` file to the root of their source tree with the ``build_type`` flag set to ``cmake`` and appropriate ``build_depend`` and ``run_depend`` tags set, as described in `REP-0136 `_. +This can been done to build packages like ``opencv``, ``pcl``, and ``flann``. Workspace Chaining / Extending ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -An important property listed in the configuration configuration which deserves -attention is the summary value of the ``Extending`` property. This affects -which other collections of libraries and packages which will be visible to your -workspace. This is process called "workspace chaining." +An important property listed in the configuration configuration which deserves attention is the summary value of the ``Extending`` property. +This affects which other collections of libraries and packages which will be visible to your workspace. +This is process called "workspace chaining." -Above, it's mentioned that the Catkin setup files export numerous environment -variables, including ``CMAKE_PREFIX_PATH``. Since CMake 2.6.0, the -``CMAKE_PREFIX_PATH`` is used when searching for include files, binaries, or -libraries using the ``FIND_PACKAGE()``, ``FIND_PATH()``, ``FIND_PROGRAM()``, or -``FIND_LIBRARY()`` CMake commands. +Above, it's mentioned that the Catkin setup files export numerous environment variables, including ``CMAKE_PREFIX_PATH``. +Since CMake 2.6.0, the ``CMAKE_PREFIX_PATH`` is used when searching for include files, binaries, or libraries using the ``FIND_PACKAGE()``, ``FIND_PATH()``, ``FIND_PROGRAM()``, or ``FIND_LIBRARY()`` CMake commands. As such, this is also the primary way that Catkin "chains" workspaces together. -When you build a Catkin workspace for the first time, it will automatically use -``CMAKE_PREFIX_PATH`` to find dependencies. After that compilation, the value -will be cached internally by each project as well as the Catkin setup files and -they will ignore any changes to your ``CMAKE_PREFIX_PATH`` environment variable -until they are cleaned. +When you build a Catkin workspace for the first time, it will automatically use ``CMAKE_PREFIX_PATH`` to find dependencies. +After that compilation, the value will be cached internally by each project as well as the Catkin setup files and they will ignore any changes to your ``CMAKE_PREFIX_PATH`` environment variable until they are cleaned. .. note:: - Workspace **chaining** is the act of putting the products of one workspace - ``A`` in the search scope of another workspace ``B``. When describing the - relationship between two such chained workspaces, ``A`` and ``B``, it is said - that workspace ``B`` **extends** workspace ``A`` and workspace ``A`` is - **extended by** workspace ``B``. This concept is also sometimes referred to - as "overlaying" or "inheriting" a workspace. - -Similarly, when you ``source`` a Catkin workspace's setup file from a -workspace's **devel space** or **install space**, it prepends the path -containing that setup file to the ``CMAKE_PREFIX_PATH`` environment variable. -The next time you initialize a workspace, it will extend the workspace that you -previously sourced. - -On one hand, this makes it easy and automatic to chain workspaces. At the same -time, however, previous tools like ``catkin_make`` and ``catkin_make_isolated`` -had no easy mechanism for either making it obvious which workspace was being -extended, nor did they provide features to explicitly extend a given workspace. -This means that for users unaware of Catkin's use of ``CMAKE_PREFIX_PATH`` - -Since it's not expected that 100% of users will read this section of the -documentation, the ``catkin`` program adds both configuration consistency -checking for the value of ``CMAKE_PREFIX_PATH`` and makes it obvious on each -invocation which workspace is being extended. Furthermore, the ``catkin`` -command adds an explicit extension interface to override the value of -``$CMAKE_PREFIX_PATH`` with the ``catkin config --extend`` command. + Workspace **chaining** is the act of putting the products of one workspace ``A`` in the search scope of another workspace ``B``. + When describing the relationship between two such chained workspaces, ``A`` and ``B``, it is said that workspace ``B`` **extends** workspace ``A`` and workspace ``A`` is **extended by** workspace ``B``. + This concept is also sometimes referred to as "overlaying" or "inheriting" a workspace. -.. note:: +Similarly, when you ``source`` a Catkin workspace's setup file from a workspace's **devel space** or **install space**, it prepends the path containing that setup file to the ``CMAKE_PREFIX_PATH`` environment variable. +The next time you initialize a workspace, it will extend the workspace that you previously sourced. + +This makes it easy and automatic to chain workspaces. +Previous tools like ``catkin_make`` and ``catkin_make_isolated`` had no easy mechanism for either making it obvious which workspace was being extended, nor did they provide features to explicitly extend a given workspace. +This means that for users were unaware of Catkin's use of ``CMAKE_PREFIX_PATH``. + +Since it's not expected that 100% of users will read this section of the documentation, the ``catkin`` program adds both configuration consistency checking for the value of ``CMAKE_PREFIX_PATH`` and makes it obvious on each invocation which workspace is being extended. +Furthermore, the ``catkin`` command adds an explicit extension interface to override the value of ``$CMAKE_PREFIX_PATH`` with the ``catkin config --extend`` command. - While workspaces can be chained together to add search paths, invoking a - build in one workspace will not cause products in any other workspace to be - built. + .. note:: -The information about which workspace to extend can come from a few different -sources, and can be classified in one of three ways: + While workspaces can be chained together to add search paths, invoking a build in one workspace will not cause products in any other workspace to be built. + +The information about which workspace to extend can come from a few different sources, and can be classified in one of three ways: No Chaining ----------- -This is what is shown in the above example configuration and it implies that -there are no other Catkin workspaces which this workspace extends. The user has -neither explicitly specified a workspace to extend, and the -``CMAKE_PREFIX_PATH`` environment variable is empty: +This is what is shown in the above example configuration and it implies that there are no other Catkin workspaces which this workspace extends. +The user has neither explicitly specified a workspace to extend, and the ``CMAKE_PREFIX_PATH`` environment variable is empty: .. code-block:: bash @@ -397,43 +315,31 @@ neither explicitly specified a workspace to extend, and the Implicit Chaining via ``CMAKE_PREFIX_PATH`` Environment or Cache Variable ------------------------------------------------------------------------- -In this case, the ``catkin`` command is *implicitly* assuming that you want -to build this workspace against resources which have been built into the -directories listed in your ``CMAKE_PREFIX_PATH`` environment variable. As -such, you can control this value simply by changing this environment -variable. +In this case, the ``catkin`` command is *implicitly* assuming that you want to build this workspace against resources which have been built into the directories listed in your ``CMAKE_PREFIX_PATH`` environment variable. +As such, you can control this value simply by changing this environment variable. -For example, ROS users who load their system's installed ROS environment by -calling something similar to ``source /opt/ros/hydro/setup.bash`` will -normally see an ``Extending`` value such as: +For example, ROS users who load their system's installed ROS environment by calling something similar to ``source /opt/ros/indigo/setup.bash`` will normally see an ``Extending`` value such as: .. code-block:: bash - Extending: [env] /opt/ros/hydro - -If you don't want to extend the given workspace, unsetting the -``CMAKE_PREFIX_PATH`` environment variable will change it back to none. You can -also alternatively + Extending: [env] /opt/ros/indigo -Once you have built your workspace once, this ``CMAKE_PREFIX_PATH`` will be -cached by the underlying CMake buildsystem. As such, the ``Extending`` status -will subsequently describe this as the "cached" extension path: +If you don't want to extend the given workspace, unsetting the ``CMAKE_PREFIX_PATH`` environment variable will change it back to none. +Once you have built your workspace once, this ``CMAKE_PREFIX_PATH`` will be cached by the underlying CMake buildsystem. +As such, the ``Extending`` status will subsequently describe this as the "cached" extension path: .. code-block:: bash - Extending: [cached] /opt/ros/hydro + Extending: [cached] /opt/ros/indigo -Once the extension mode is cached like this, you must use ``catkin clean`` to -before changing it to something else. +Once the extension mode is cached like this, you must use ``catkin clean`` to before changing it to something else. Explicit Chaining via ``catkin config --extend`` ------------------------------------------------ -This behaves like the above implicit chaining except it means that this -workspace is *explicitly* extending another workspace and the workspaces -which the other workspace extends, recursively. This can be set with the -``catkin config --extend`` command. It will override the value of -``CMAKE_PREFIX_PATH`` and persist between builds. +This behaves like the above implicit chaining except it means that this workspace is *explicitly* extending another workspace and the workspaces which the other workspace extends, recursively. +This can be set with the ``catkin config --extend`` command. +It will override the value of ``CMAKE_PREFIX_PATH`` and persist between builds. .. code-block:: bash diff --git a/docs/migration.rst b/docs/migration.rst index 1fb132e4..3f655e38 100644 --- a/docs/migration.rst +++ b/docs/migration.rst @@ -4,60 +4,44 @@ Migrating from catkin_make Important Distinctions between ``catkin_make`` and ``catkin build`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Unlike ``catkin_make``, the ``catkin`` command-line tool is not just a thin -wrapper around a ``CMake`` use pattern. The ``catkin build`` command builds -each package in a workspace's source space *in isolation* in order to prevent -buildtime cross-talk. As such, in its simplest use, ``catkin build`` is like a -parallelized version of ``catkin_make_isolated``. While there are many more -features in ``catkin_tools`` described in the rest of the documentation, this -chapter provides details on how to switch from using ``catkin_make`` or -``catkin_make_isolated``. +Unlike ``catkin_make``, the ``catkin`` command-line tool is not just a thin wrapper around a ``CMake`` use pattern. +The ``catkin build`` command builds each package in a workspace's source space *in isolation* in order to prevent buildtime cross-talk. +As such, in its simplest use, ``catkin build`` is like a parallelized version of ``catkin_make_isolated``. +While there are many more features in ``catkin_tools`` described in the rest of the documentation, this chapter provides details on how to switch from using ``catkin_make`` or ``catkin_make_isolated``. Operational Differences ^^^^^^^^^^^^^^^^^^^^^^^ -- ``catkin_tools`` has no "top-level" ``CMakeLists.txt`` file. The **source - space** simply contains a collection of packages. If you have been modifying - this ``CMakeLists.txt`` file, those modifications will be ignored. +- ``catkin_tools`` has no "top-level" ``CMakeLists.txt`` file. + The **source space** simply contains a collection of packages. + If you have been modifying this ``CMakeLists.txt`` file, those modifications will be ignored. - Each package in a ``catkin_tools`` workspace has its own isolated build space. - ``catkin build`` can be run from any directory under the workspace root -- ``catkin config`` stores many workspace configuration options which needed to - be passed to each call of ``catkin_make`` -- ``catkin build`` can build plain CMake packages if they have ``package.xml`` - files -- Packages built with ``catkin build`` can not access variables defined in - other Catkin packages in the same workspace. -- Packages no longer need to define target dependencies on ROS messages built - in other packages. All targets in a dependency are guaranteed to have been - built before the current package. -- ``catkin_tools`` and ``catkin_make`` can use the same source space, but they - must use different build, devel, and install spaces. -- ``catkin build`` generates ``.catkin`` files and subsequently - ``ROS_PACKAGE_PATH`` variables where each source package is listed, individually, - instead of just listing the source space for the workspace. +- ``catkin config`` stores many workspace configuration options which needed to be passed to each call of ``catkin_make`` +- ``catkin build`` can build plain CMake packages if they have ``package.xml`` files +- Packages built with ``catkin build`` can not access variables defined in other Catkin packages in the same workspace. +- Packages no longer need to define target dependencies on ROS messages built in other packages. + All targets in a dependency are guaranteed to have been built before the current package. +- ``catkin_tools`` and ``catkin_make`` can use the same source space, but they must use different build, devel, and install spaces. +- ``catkin build`` generates ``.catkin`` files and subsequently ``ROS_PACKAGE_PATH`` variables where each source package is listed, individually, instead of just listing the source space for the workspace. - ``catkin build`` passes CMake command line arguments to multiple packages. - Since not all packages accept the same CMake arguments, the ``cmake`` command - is invoked with ``--no-warn-unused-cli``. This means there will be no warnings - for unused variables passed to ``cmake``. + Since not all packages accept the same CMake arguments, the ``cmake`` command is invoked with ``--no-warn-unused-cli``. + This means there will be no warnings for unused variables passed to ``cmake``. IDE Integration ^^^^^^^^^^^^^^^ -Since all packages are built in isolation with ``catkin build``, you can't rely -on CMake's IDE integration to generate a single project for your entire workspace. +Since all packages are built in isolation with ``catkin build``, you can't rely on CMake's IDE integration to generate a single project for your entire workspace. .. _migration-troubleshooting: Migration Troubleshooting ^^^^^^^^^^^^^^^^^^^^^^^^^ -When migrating from ``catkin_make`` to catkin build, the most common problems -come from Catkin packages taking advantge of package cross-talk in the CMake -configuration stage. +When migrating from ``catkin_make`` to catkin build, the most common problems come from Catkin packages taking advantge of package cross-talk in the CMake configuration stage. -Many Catkin packages implicitly rely on other packages in a workspace to -declare and find dependencies. When switcing from ``catkin_make``, users -will often discover these bugs. +Many Catkin packages implicitly rely on other packages in a workspace to declare and find dependencies. +When switcing from ``catkin_make``, users will often discover these bugs. Common Issues ------------- @@ -65,51 +49,41 @@ Common Issues Unknown CMake command "catkin_package" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If ``find_package(catkin REQUIRED ...)`` isn't called, then the -``catkin_package()`` macro will not be available. If such a package builds with -``catkin_make``, it's because it's relying on another package in the same -workspace to do this work. +If ``find_package(catkin REQUIRED ...)`` isn't called, then the ``catkin_package()`` macro will not be available. +If such a package builds with ``catkin_make``, it's because it's relying on another package in the same workspace to do this work. Compilation Errors (Missing Headers) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Compilation errors can occur if required headers are not found. If -your package includes headers from ``${catkin_INCLUDE_DIRS}``, make sure *that* -package is finding the right Catkin packages in ``find_package(catkin -COMPONENTS ...)``. +Compilation errors can occur if required headers are not found. +If your package includes headers from ``${catkin_INCLUDE_DIRS}``, make sure *that* package is finding the right Catkin packages in ``find_package(catkin COMPONENTS ...)``. -If your package includes headers from other libraries, make sure those -libraries are found and those CMake variables are defined. +If your package includes headers from other libraries, make sure those libraries are found and those CMake variables are defined. Linker Errors (Undefined References) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Linker errors are due to targets not being linked to required libraries. If -your target links against ``${catkin_LIBRARIES}``, make sure *that* package -is finding the right Catkin packages in ``find_package(catkin COMPONENTS ...)``. +Linker errors are due to targets not being linked to required libraries. +If your target links against ``${catkin_LIBRARIES}``, make sure *that* package is finding the right Catkin packages in ``find_package(catkin COMPONENTS ...)``. -If your target links against other libraries, make sure those libraries are -found and those CMake variables are defined. +If your target links against other libraries, make sure those libraries are found and those CMake variables are defined. - https://github.com/catkin/catkin_tools/issues/228 Targets Not Being Built ~~~~~~~~~~~~~~~~~~~~~~~ -It is critical for Catkin-based packages to call ``catkin_package()`` before -**any** targets are defined. Otherwise your targets will not be built into the -**devel space**. Previously with ``catkin_make``, as long as some package -called ``catkin_package()`` before your package was configured, the appropriate -target destinations were defined. +It is critical for Catkin-based packages to call ``catkin_package()`` before **any** targets are defined. +Otherwise your targets will not be built into the **devel space**. +Previously with ``catkin_make``, as long as some package called ``catkin_package()`` before your package was configured, the appropriate target destinations were defined. - https://github.com/catkin/catkin_tools/issues/220 Compiler Options Aren't Correct ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Your program might fail to build or fail to run due to incorrect compiler -options. Sometimes these compiler options are needed to use a dependency, but -aren't made available to the dependant package. +Your program might fail to build or fail to run due to incorrect compiler options. +Sometimes these compiler options are needed to use a dependency, but aren't made available to the dependant package. With ``catkin_make``, if a package sets certain compiler options, such as: @@ -117,17 +91,13 @@ With ``catkin_make``, if a package sets certain compiler options, such as: set(CMAKE_CXX_FLAGS "-std=c++ ${CMAKE_CXX_FLAGS}") -These options will be set for every package in the topological sort which is -built after it, even packages which don't depend on it. +These options will be set for every package in the topological sort which is built after it, even packages which don't depend on it. -With ``catkin build``, however, these effects are isolated, so even the packages -that need these options will not get them. The ``catkin_package()`` macro already -provides options for exporting libraries and include directories, but it does not -have an option for CMake variables. +With ``catkin build``, however, these effects are isolated, so even the packages that need these options will not get them. +The ``catkin_package()`` macro already provides options for exporting libraries and include directories, but it does not have an option for CMake variables. -To export such settings (or even execute code), the ``CFG_EXTRAS`` option -must be used with an accompanying CMake file. For more information on this option, -see `the catkin_package() documentation `_. +To export such settings (or even execute code), the ``CFG_EXTRAS`` option must be used with an accompanying CMake file. +For more information on this option, see `the catkin_package() documentation `_. - https://github.com/catkin/catkin_tools/issues/210 - https://github.com/carpe-noctem-cassel/cnc-msl/pull/1 @@ -138,22 +108,15 @@ Uncommon Issues Exporting Build Utilities ~~~~~~~~~~~~~~~~~~~~~~~~~ -Some Catkin packages provide build tools at configuration time, like scripts -for generating code or downloading resources from the internet. These -packages need to export absolute paths to such tools both when used in a -workspace and when installed. +Some Catkin packages provide build tools at configuration time, like scripts for generating code or downloading resources from the internet. +These packages need to export absolute paths to such tools both when used in a workspace and when installed. -For example, when using in a source space, the build tools from package -``my_build_util`` would be found at ``${CMAKE_CURRENT_SOURCE_DIR}/cmake``, but -when installed, they would be found in ``${my_build_util_DIR}``. +For example, when using in a source space, the build tools from package ``my_build_util`` would be found at ``${CMAKE_CURRENT_SOURCE_DIR}/cmake``, but when installed, they would be found in ``${my_build_util_DIR}``. -With ``catkin_make``, the path to these tools could be set to either the source -or install space in the provider package just by setting a CMake variable, which -would be "leaked" to all subsequently built packages. +With ``catkin_make``, the path to these tools could be set to either the source or install space in the provider package just by setting a CMake variable, which would be "leaked" to all subsequently built packages. -With ``catkin build``, these paths need to be properly exported with -``CFG_EXTRAS``. A way to do this that works both out of a workspace and install -is shown below: +With ``catkin build``, these paths need to be properly exported with ``CFG_EXTRAS``. +A way to do this that works both out of a workspace and install is shown below: .. code-block:: cmake :caption: my_build_util-extras.cmake.em @@ -172,13 +135,10 @@ is shown below: Exporting Non-Standard Library Output Locations or Prefixes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Some users may choose to build library targets with non-standard output -locations or prefixes. However, the normal ``catkin_package()`` macro -cannot export libraries with such paths across packages. +Some users may choose to build library targets with non-standard output locations or prefixes. +However, the normal ``catkin_package()`` macro cannot export libraries with such paths across packages. -Again, we can use the ``CFG_EXTRAS`` option to append the special library to -the ``${PROJECT_NAME}_LIBRARIES`` variable that ``catkin_package()`` exports to -other packages. +Again, we can use the ``CFG_EXTRAS`` option to append the special library to the ``${PROJECT_NAME}_LIBRARIES`` variable that ``catkin_package()`` exports to other packages. .. code-block:: cmake :caption: CMakeLists.txt @@ -194,7 +154,7 @@ other packages. PREFIX "" LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION} ) - + .. code-block:: cmake :caption: my.cmake.in @@ -223,14 +183,10 @@ other packages. Controlling Python Version ~~~~~~~~~~~~~~~~~~~~~~~~~~ -On some platforms, there are multiple versions of Python, and Catkin's -internal setup file generation might pick the wrong one. For ``catkin_make``, -this is sometimes solved on a given platform by creating a shell alias which -sets the ``PYTHON_EXECUTABLE`` CMake variable. +On some platforms, there are multiple versions of Python, and Catkin's internal setup file generation might pick the wrong one. +For ``catkin_make``, this is sometimes solved on a given platform by creating a shell alias which sets the ``PYTHON_EXECUTABLE`` CMake variable. -For ``catkin build``, however, you can create a *verb alias* like the one -below, which overrides the default behavior of ``catkin build`` even in new -workspaces. +For ``catkin build``, however, you can create a *verb alias* like the one below, which overrides the default behavior of ``catkin build`` even in new workspaces. .. code-block:: yaml @@ -243,42 +199,41 @@ See :doc:`Verb Aliasing ` for more details. CLI Comparison with ``catkin_make`` and ``catkin_make_isolated`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Below are tables mapping ``catkin_make`` and ``catkin_make_isolated`` arguments -into ``catkin`` arguments. Note that some ``catkin_make`` options can only be -achived with the ``catkin config`` verb. +Below are tables mapping ``catkin_make`` and ``catkin_make_isolated`` arguments into ``catkin`` arguments. +Note that some ``catkin_make`` options can only be achived with the ``catkin config`` verb. ================================================= ============================================ - catkin_make ... catkin ... + catkin_make ... catkin ... ================================================= ============================================ - ``-C PATH`` ``-w PATH [build | config | ...]`` + ``-C PATH`` ``-w PATH [build | config | ...]`` ------------------------------------------------- -------------------------------------------- - ``--source PATH`` ``config --source-space PATH`` [1]_ + ``--source PATH`` ``config --source-space PATH`` [1]_ ------------------------------------------------- -------------------------------------------- - ``--build PATH`` ``config --build-space PATH`` [1]_ + ``--build PATH`` ``config --build-space PATH`` [1]_ ------------------------------------------------- -------------------------------------------- - ``--use-ninja`` *not yet available* + ``--use-ninja`` *not yet available* ------------------------------------------------- -------------------------------------------- - ``--force-cmake`` ``build --force-cmake`` + ``--force-cmake`` ``build --force-cmake`` ------------------------------------------------- -------------------------------------------- - ``--pkg PKG [PKG ...]`` ``build --no-deps PKG [PKG ...]`` + ``--pkg PKG [PKG ...]`` ``build --no-deps PKG [PKG ...]`` ------------------------------------------------- -------------------------------------------- - ``--only-pkg-with-deps PKG [PKG ...]`` ``build PKG [PKG ...]`` + ``--only-pkg-with-deps PKG [PKG ...]`` ``build PKG [PKG ...]`` ------------------------------------------------- -------------------------------------------- ``--cmake-args ARG [ARG ...]`` ``build --cmake-args ARG [ARG ...]`` [2]_ ------------------------------------------------- -------------------------------------------- - ``--make-args ARG [ARG ...]`` ``build --make-args ARG [ARG ...]`` [2]_ + ``--make-args ARG [ARG ...]`` ``build --make-args ARG [ARG ...]`` [2]_ ------------------------------------------------- -------------------------------------------- - ``--override-build-tool-check`` ``build --override-build-tool-check`` + ``--override-build-tool-check`` ``build --override-build-tool-check`` ------------------------------------------------- -------------------------------------------- - ``ARG [ARG ...]`` ``build --make-args ARG [ARG ...]`` + ``ARG [ARG ...]`` ``build --make-args ARG [ARG ...]`` ------------------------------------------------- -------------------------------------------- - ``install`` ``config --install`` [1]_ + ``install`` ``config --install`` [1]_ ------------------------------------------------- -------------------------------------------- - ``-DCATKIN_DEVEL_PREFIX=PATH`` ``config --devel-space PATH`` [1]_ + ``-DCATKIN_DEVEL_PREFIX=PATH`` ``config --devel-space PATH`` [1]_ ------------------------------------------------- -------------------------------------------- - ``-DCATKIN_INSTALL_PREFIX=PATH`` ``config --install-space PATH`` [1]_ + ``-DCATKIN_INSTALL_PREFIX=PATH`` ``config --install-space PATH`` [1]_ ------------------------------------------------- -------------------------------------------- - ``-DCATKIN_WHITELIST_PACKAGES="PKG[;PKG ...]"`` ``config --whitelist PKG [PKG ...]`` [1]_ + ``-DCATKIN_WHITELIST_PACKAGES="PKG[;PKG ...]"`` ``config --whitelist PKG [PKG ...]`` [1]_ ================================================= ============================================ diff --git a/docs/quick_start.rst b/docs/quick_start.rst index c5cc892f..7ddcfa47 100644 --- a/docs/quick_start.rst +++ b/docs/quick_start.rst @@ -1,17 +1,14 @@ Quickstart ========== -This chapter gives a high-level overview of how to use ``catkin_tools`` and the -``catkin`` command. This shows how to use the different command verbs to create -and manipulate a workspace. For a more in-depth explanation of the mechanics of -catkin workspaces, see :doc:`Workspace Mechanics `, and for thorogh -usage details see the individual verb documentation. +This chapter gives a high-level overview of how to use ``catkin_tools`` and the ``catkin`` command. +This shows how to use the different command verbs to create and manipulate a workspace. +For a more in-depth explanation of the mechanics of catkin workspaces, see :doc:`Workspace Mechanics `, and for thorough usage details see the individual verb documentation. TL;DR ^^^^^ -The following is an example workflow and sequence of commands using default -settings: +The following is an example workflow and sequence of commands using default settings: .. literalinclude:: examples/quickstart_ws/0_quickstart.bash :language: bash @@ -23,39 +20,31 @@ settings: Initializing a New Workspace ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -While initialization of a workspace can be done automatically with ``catkin -build``, it's good practice to initialize a catkin workspace explicitly. -This is done by simply creating a new workspace with an empty **source space** -(named ``src`` by default) and calling ``catkin init`` from the workspace root: +While initialization of a workspace can be done automatically with ``catkin build``, it's good practice to initialize a catkin workspace explicitly. +This is done by simply creating a new workspace with an empty **source space** (named ``src`` by default) and calling ``catkin init`` from the workspace root: .. literalinclude:: examples/quickstart_ws/0_quickstart.bash :language: bash :lines: 1-4 -Now the directory ``/tmp/quickstart-init`` has been initialized and ``catkin -init`` has printed the standard configuration summary to the console with the -default values. This summary describes the layout of the workspace as well as -other important settings which influence build and execution behavior. +Now the directory ``/tmp/quickstart-init`` has been initialized and ``catkin init`` has printed the standard configuration summary to the console with the default values. +This summary describes the layout of the workspace as well as other important settings which influence build and execution behavior. -Once a workspace has been initialized, the configuration summary can be -displayed by calling ``catkin config`` without arguments from anywhere under -the root of the workspace. Doing so will not modify your workspace. The -``catkin`` command is context-sensitive, so it will determine which workspace -contains the current working directory. +Once a workspace has been initialized, the configuration summary can be displayed by calling ``catkin config`` without arguments from anywhere under the root of the workspace. +Doing so will not modify your workspace. +The ``catkin`` command is context-sensitive, so it will determine which workspace contains the current working directory. -An important property which deserves attention is the summary value labeled -``Extending``. This describes other collections of libraries and packages which -will be visible to your workspace. This is process called "workspace chaining." -The value can be come from a few different sources, and can be classified in -one of the three following ways: +An important property which deserves attention is the summary value labeled ``Extending``. +This describes other collections of libraries and packages which will be visible to your workspace. +This is process called "workspace chaining." +The value can come from a few different sources, and can be classified in one of the three following ways: - No chaining - Implicit chaining via ``CMAKE_PREFIX_PATH`` environment or cache variable - Explicit chaining via ``catkin config --extend`` -For more information on the configuration summary and workspace chaining, see -:doc:`Configuration Summary `. For information on manipulating -these options, see :doc:`the config verb `. +For more information on the configuration summary and workspace chaining, see :doc:`Configuration Summary `. +For information on manipulating these options, see :doc:`the config verb `. .. note:: @@ -67,21 +56,18 @@ these options, see :doc:`the config verb `. Adding Packages to the Workspace ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to build software with Catkin, it needs to be added to the workspace's -**source space**. You can either download some existing packages, or create one -or more empty ones. As shown above, the default path for a Catkin **source -space** is `./src` relative to the workspace root. A standard Catkin package is -simply a directory with a ``CMakeLists.txt`` file and a ``package.xml`` file. -For more information on Catkin packages see :doc:`workspace mechanics -`. The shell interaction below shows the creation of four -empty packages: ``pkg_a``, ``pkg_b``, ``pkg_c``, and ``pkg_d``: +In order to build software with Catkin, it needs to be added to the workspace's **source space**. +You can either download some existing packages, or create one or more empty ones. +As shown above, the default path for a Catkin **source space** is `./src` relative to the workspace root. +A standard Catkin package is simply a directory with a ``CMakeLists.txt`` file and a ``package.xml`` file. +For more information on Catkin packages see :doc:`workspace mechanics `. +The shell interaction below shows the creation of four empty packages: ``pkg_a``, ``pkg_b``, ``pkg_c``, and ``pkg_d``: .. literalinclude:: examples/quickstart_ws/0_quickstart.bash :language: bash :lines: 5-10 -After these operations, your workspace's local directory structure would look like -the followng (to two levels deep): +After these operations, your workspace's local directory structure would look like the followng (to two levels deep): .. literalinclude:: examples/quickstart_ws/1_prebuild.bash :language: bash @@ -93,30 +79,22 @@ Now that there are some packages in the workspace, Catkin has something to build .. note:: - Catkin utilizes an "out-of-source" and "aggregated" build pattern. This - means that not only will temporary or final build products never be placed - in a package's source directory (or anywhere in the **source space** for - that matter), but also all build directories are aggregated in the **build - space** and all final build products (executables, libraries, etc.) will be - put in the **devel space**. + Catkin utilizes an "out-of-source" and "aggregated" build pattern. + This means that temporary or final build will products never be placed in a package's source directory (or anywhere in the **source space**. + Instead all build directories are aggregated in the **build space** and all final build products like executables, libraries, etc., will be put in the **devel space**. Building the Workspace ^^^^^^^^^^^^^^^^^^^^^^ -Since the catkin workspace has already been initialized, you can call ``catkin -build`` from any directory contained within it. If it had not been initialized, -then ``catkin build`` would need to be called from the workspace root. Based on -the default configuration, it will locate the packages in the **source space** -and build each of them. +Since the catkin workspace has already been initialized, you can call ``catkin build`` from any directory contained within it. +If it had not been initialized, then ``catkin build`` would need to be called from the workspace root. +Based on the default configuration, it will locate the packages in the **source space** and build each of them. .. literalinclude:: examples/quickstart_ws/0_quickstart.bash :language: bash :lines: 11 - -Calling ``catkin build`` will generate ``build`` and ``devel`` directories (as -described in the config summary above) and result in a directory structure like -the following (to one level deep): +Calling ``catkin build`` will generate ``build`` and ``devel`` directories (as described in the config summary above) and result in a directory structure like the following (up to one level deep): .. literalinclude:: examples/quickstart_ws/2_postbuild.bash :language: bash @@ -124,25 +102,19 @@ the following (to one level deep): .. literalinclude:: examples/quickstart_ws/2_postbuild.bash.out :language: text -Intermediate build products (CMake cache files, Makefiles, object files, etc.) -are generated in the ``build`` directory, or **build space** and final build -products (libraries, executables, config files) are generated in the ``devel`` -directory, or **devel space**. For more information on building and customizing -the build configuration see the :doc:`build verb ` and -:doc:`config verb ` documentation. +Intermediate build products (CMake cache files, Makefiles, object files, etc.) are generated in the ``build`` directory, or **build space** and final build products (libraries, executables, config files) are generated in the ``devel`` directory, or **devel space**. +For more information on building and customizing the build configuration see the :doc:`build verb ` and :doc:`config verb ` documentation. Loading the Workspace Environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to properly "use" the products of the workspace, it's environment needs -to be loaded. Among other environment variables, sourcing a Catkin setup file -modifies the ``CMAKE_PREFIX_PATH`` environment variable, which will affect -workspace chaining as described in the earlier section. +In order to properly "use" the products of the workspace, its environment needs to be loaded. +Among other environment variables, sourcing a Catkin setup file modifies the ``CMAKE_PREFIX_PATH`` environment variable, which will affect workspace chaining as described in the earlier section. -Setup files are located in one of the **result spaces** generated by your -workspace. Both the **devel space** or the **install space** are valid **result -spaces**. In the default build configuration, only the **devel space** is -generated. You can load the environment for your respective shell like so: +Setup files are located in one of the **result spaces** generated by your workspace. +Both the **devel space** or the **install space** are valid **result spaces**. +In the default build configuration, only the **devel space** is generated. +You can load the environment for your respective shell like so: .. literalinclude:: examples/quickstart_ws/0_quickstart.bash :language: bash @@ -156,33 +128,24 @@ in your workspace. Any time the member packages change in your workspace, you will need to re-run the source command. -Loading the environment from a Catkin workspace can set **arbitrarily many** -environment variables, depending on which "environment hooks" the member -packages define. As such, it's important to know which workspace environment is -loaded in a given shell. +Loading the environment from a Catkin workspace can set **arbitrarily many** environment variables, depending on which "environment hooks" the member packages define. +As such, it's important to know which workspace environment is loaded in a given shell. -It's not unreasonable to automatically source a given setup file in each shell -for convenience, but if you do so, it's good practice to pay attention to the -``Extending`` value in the Catkin config summary. Any Catkin setup file will -modify the ``CMAKE_PREFIX_PATH`` environment variable, and the config summary -should catch common inconsistencies in the environment. +It's not unreasonable to automatically source a given setup file in each shell for convenience, but if you do so, it's good practice to pay attention to the ``Extending`` value in the Catkin config summary. +Any Catkin setup file will modify the ``CMAKE_PREFIX_PATH`` environment variable, and the config summary should catch common inconsistencies in the environment. Cleaning Workspace Products ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Instead of using dangerous commands like ``rm -rf build devel`` in your -workspace when cleaning build products, you can use the ``catkin clean --all`` -command. Just like the other verbs, ``catkin clean`` is context-aware, so it -only needs to be called from a directory under the workspace root. +Instead of using dangerous commands like ``rm -rf build devel`` in your workspace when cleaning build products, you can use the ``catkin clean --all`` command. +Just like the other verbs, ``catkin clean`` is context-aware, so it only needs to be called from a directory under the workspace root. -In order to clean the **build space** and **devel space** for the workspace, -you can use the following command: +In order to clean the **build space** and **devel space** for the workspace, you can use the following command: .. literalinclude:: examples/quickstart_ws/0_quickstart.bash :language: bash :lines: 13 -For more information on less aggressive cleaning options see the :doc:`clean -verb ` documentation. +For more information on less aggressive cleaning options see the :doc:`clean verb ` documentation. diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 918d7bdd..4d499038 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -4,10 +4,9 @@ Troubleshooting Configuration Summary Warnings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The ``catkin`` tool is capable of detecting some issues or inconsistencies with -the build configuration automatically. In these cases, it will often describe -the problem as well as how to resolve it. The ``catkin`` tool will detect the -following issues automatically. +The ``catkin`` tool is capable of detecting some issues or inconsistencies with the build configuration automatically. +In these cases, it will often describe the problem as well as how to resolve it. +The ``catkin`` tool will detect the following issues automatically. Missing Workspace Components ---------------------------- @@ -29,15 +28,12 @@ Dependency Resolution Packages Are Being Built Out of Order ------------------------------------- -- The ``package.xml`` dependency tags are most likely incorrect. Note that - dependencies are only used to order the packages, and there is no warning if - a package can't be found. -- Run ``catkin list --deps /path/to/ws/src`` to list the dependencies of each - package and look for errors. +- The ``package.xml`` dependency tags are most likely incorrect. + Note that dependencies are only used to order the packages, and there is no warning if a package can't be found. +- Run ``catkin list --deps /path/to/ws/src`` to list the dependencies of each package and look for errors. Migration Problems ^^^^^^^^^^^^^^^^^^ -For troubleshooting problems when migrating from ``catkin_make`` or -``catkin_make_isolated``, see :ref:`migration-troubleshooting`. +For troubleshooting problems when migrating from ``catkin_make`` or ``catkin_make_isolated``, see :ref:`migration-troubleshooting`. diff --git a/docs/verbs/catkin_build.rst b/docs/verbs/catkin_build.rst index ed28c8a9..67a7deb2 100644 --- a/docs/verbs/catkin_build.rst +++ b/docs/verbs/catkin_build.rst @@ -2,18 +2,14 @@ ================================== The ``build`` verb is used to build one or more packages in a catkin workspace. -Like most verbs, ``build`` is context-aware and can be executed from within any -directory contained by an initialized workspace. If a workspace is not yet -initialized, ``build`` can initialize it with the default configuration, but -only if it is called from the workspace root. Specific workspaces can also be -built from arbitrary working directories with the ``--workspace`` option. +Like most verbs, ``build`` is context-aware and can be executed from within any directory contained by an initialized workspace. +If a workspace is not yet initialized, ``build`` can initialize it with the default configuration, but only if it is called from the workspace root. +Specific workspaces can also be built from arbitrary working directories with the ``--workspace`` option. .. note:: - To set up a workspace and clone the repositories used in the following - examples, you can use `rosinstall_generator `_ and `wstool `_. - The following clones all of the ROS packages necessary for building the - introductory ROS tutorials: + To set up a workspace and clone the repositories used in the following examples, you can use `rosinstall_generator `_ and `wstool `_. + The following clones all of the ROS packages necessary for building the introductory ROS tutorials: .. literalinclude:: ../examples/ros_tutorials_ws/0_checkout.bash :language: bash @@ -24,15 +20,13 @@ Basic Usage Previewing The Build -------------------- -Before actually building anything in the workspace, it is useful to preview -which packages will be built and in what order. This can be done with the -``--dry-run`` option: +Before actually building anything in the workspace, it is useful to preview which packages will be built and in what order. +This can be done with the ``--dry-run`` option: .. literalinclude:: ../examples/ros_tutorials_ws/2_dry_run.bash :language: bash -In addition to the listing the package names and in which order they would be -built, it also displays the build type of each package. +In addition to the listing the package names and in which order they would be built, it also displays the build type of each package. .. raw:: html @@ -51,17 +45,11 @@ It automatically creates directories for a **build space** and a **devel space**
-After the build finishes, the **build space** contains directories containing -the intermediate build products for each package, and the **devel space** -contains an FHS layout into which all the final build products are written. +After the build finishes, the **build space** contains directories containing the intermediate build products for each package, and the **devel space** contains an FHS layout into which all the final build products are written. .. note:: - The products of ``catkin build`` differ significantly from the behavior of - ``catkin_make``, for example, which would have all of the build files and - intermediate build products in a combined **build space** or - ``catkin_make_isolated`` which would have an isolated FHS directory for - each package in the **devel space**. + The products of ``catkin build`` differ significantly from the behavior of ``catkin_make``, for example, which would have all of the build files and intermediate build products in a combined **build space** or ``catkin_make_isolated`` which would have an isolated FHS directory for each package in the **devel space**. Status Line ----------- @@ -74,23 +62,14 @@ When running ``catkin build`` with default options, it displays a "live" status The status line stays at the bottom of the screen and displays the continuously-updated progress of the entire build as well as the active build jobs which are still running. It is composed of the following information: - * ``[build - ]`` -- The first block on the left indicates the total elapsed - build time ```` in seconds thus far. - * ``[/ complete]`` -- The second block from the left indicates the - build progress in terms of the number of completed packages, ```` out of - the total number of packages to be built ````. - * ``[/ jobs]`` -- The third block from the left indicates the number of - active total low-level jobs ```` out of the total number of low-level - workers ````. - * ``[ queued]`` -- The fourth block from the left indicates the number of - jobs ```` whose dependencies have already been satisfied and are ready to - be built. - * ``[ failed]`` -- The fifth block from the left indicates the number of - jobs ```` which have failed. This block only appears once one or more - jobs has failed. - * ``[: (

%) - ]`` -- The remaining blocks show details on - the active jobs. These include the percent complete, ``

``, of the stage, - if available, as well as the time elapsed building the package, ````. + * ``[build - ]`` -- The first block on the left indicates the total elapsed build time ```` in seconds thus far. + * ``[/ complete]`` -- The second block from the left indicates the build progress in terms of the number of completed packages, ```` out of the total number of packages to be built ````. + * ``[/ jobs]`` -- The third block from the left indicates the number of active total low-level jobs ```` out of the total number of low-level workers ````. + * ``[ queued]`` -- The fourth block from the left indicates the number of jobs ```` whose dependencies have already been satisfied and are ready to be built. + * ``[ failed]`` -- The fifth block from the left indicates the number of jobs ```` which have failed. + This block only appears once one or more jobs has failed. + * ``[: (

%) - ]`` -- The remaining blocks show details on the active jobs. + These include the percent complete, ``

``, of the stage, if available, as well as the time elapsed building the package, ````. When necessary, the status line can be disabled by passing the ``--no-status`` option to ``catkin build``. This is sometimes required when running ``catkin build`` from within a program that doesn't support the ASCII escape sequences required to reset and re-write the status line. @@ -98,10 +77,9 @@ This is sometimes required when running ``catkin build`` from within a program t Console Messages ---------------- -Normally, unless an error occurs, the output from each package's build proces -is collected but not printed to the console. All that is printed is a pair of -messages designating the start and end of a package's build. This is formatted -like the following for the ``genmsg`` package: +Normally, unless an error occurs, the output from each package's build proces is collected but not printed to the console. +All that is printed is a pair of messages designating the start and end of a package's build. +This is formatted like the following for the ``genmsg`` package: .. code-block:: none @@ -144,17 +122,15 @@ Additionally, if a package fails, the output to ``stderr`` is printed under the

-All of the messages from the underlying jobs can be shown when using the -``-v`` or ``--verbose`` option. This will print the normal messages when a -build job starts and finishes as well as the interleaved output to ``stdout`` -and ``stderr`` from each build command in a block. +All of the messages from the underlying jobs can be shown when using the ``-v`` or ``--verbose`` option. +This will print the normal messages when a build job starts and finishes as well as the interleaved output to ``stdout`` and ``stderr`` from each build command in a block. .. raw:: html
- -All output can be printed interleaved with the ``--interleave`` option. In this -case, each line is prefixed with the job and stage from which it came. + +All output can be printed interleaved with the ``--interleave`` option. +In this case, each line is prefixed with the job and stage from which it came. .. raw:: html @@ -163,10 +139,8 @@ case, each line is prefixed with the job and stage from which it came. Build Summary ------------- -At the end of each build, a brief build summary is printed to guarantee that -anomalies aren't missed. This summary displays the total runtime, the number -of successful jobs, the number of jobs which produced warnings, and the -number of jobs which weren't attempted due to failed dependencies. +At the end of each build, a brief build summary is printed to guarantee that anomalies aren't missed. +This summary displays the total runtime, the number of successful jobs, the number of jobs which produced warnings, and the number of jobs which weren't attempted due to failed dependencies. .. code-block:: none @@ -176,8 +150,7 @@ number of jobs which weren't attempted due to failed dependencies. [build] Abandoned: 1 jobs were abandoned. [build] Failed: 2 jobs failed. -A more detailed summary can also be printed, which lists the result for each -package in the workspace. +A more detailed summary can also be printed with the ``--summarize`` command, which lists the result for each package in the workspace. Building Subsets of Packages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -199,8 +172,7 @@ Consider a Catkin workspace with a **source space** populated with the following Building Specific Packages -------------------------- -Specific packages can also be built by specifying them as positional arguments -after the ``build`` verb: +Specific packages can also be built by specifying them as positional arguments after the ``build`` verb: .. literalinclude:: ../examples/ros_tutorials_ws/6_build_partial.bash :language: bash @@ -209,17 +181,13 @@ after the ``build`` verb:
-As shown above, only 4 packages (``roslib`` and its dependencies), of the total -36 packages would be built. +As shown above, only 4 packages (``roslib`` and its dependencies), of the total 36 packages would be built. Context-Aware Building ---------------------- -In addition to building all packages or specified packages with various -dependency requirements, ``catkin build`` can also determine the package -containing the current working directory. This is equivalent to specifying the -name of the package on the command line, and is done by passing the ``--this`` -option to ``catkin build`` like the following: +In addition to building all packages or specified packages with various dependency requirements, ``catkin build`` can also determine the package containing the current working directory. +This is equivalent to specifying the name of the package on the command line, and is done by passing the ``--this`` option to ``catkin build`` like the following: .. literalinclude:: ../examples/ros_tutorials_ws/7_build_this.bash :language: bash @@ -231,17 +199,12 @@ option to ``catkin build`` like the following: Skipping Packages ----------------- -Suppose you built every package up to ``roslib``, but that package -had a build error. -After fixing the error, you could run the same build command again, but the -``build`` verb provides an option to save time in this situation. -If re-started from the beginning, none of the products of the dependencies of -``roslib`` would be re-built, but it would still take some time for -the underlying byuildsystem to verify that for each package. +Suppose you built every package up to ``roslib``, but that package had a build error. +After fixing the error, you could run the same build command again, but the ``build`` verb provides an option to save time in this situation. +If re-started from the beginning, none of the products of the dependencies of ``roslib`` would be re-built, but it would still take some time for the underlying byuildsystem to verify that for each package. Those checks could be skipped, however, by jumping directly to a given package. -You could use the ``--start-with`` option to continue the build where you left -off after fixing the problem. +You could use the ``--start-with`` option to continue the build where you left off after fixing the problem. .. literalinclude:: ../examples/ros_tutorials_ws/8_build_start_with.bash :language: bash @@ -250,7 +213,7 @@ off after fixing the problem.
-.. note:: +.. note:: ``catkin build`` will assume that all dependencies leading up to the package specified with the ``--start-with`` option have already been successfully @@ -328,9 +291,7 @@ Advanced Options Temporarily Changing Build Flags -------------------------------- -While the build configuratoin flags are set and stored in the build context, -it's possible to temporarily override or augment them when using the ``build`` -verb. +While the build configuratoin flags are set and stored in the build context, it's possible to temporarily override or augment them when using the ``build`` verb. .. code-block:: bash @@ -352,18 +313,13 @@ This command passes the ``-DCMAKE_C_FLAGS=...`` arugment to all invocations of ` Configuring Build Jobs ---------------------- -By default ``catkin build`` on a computer with ``N`` cores will build up to -``N`` packages in parallel and will distribute ``N`` ``make`` jobs among them -using an internal jobserver. If your platform doesn't support jobserver -scheduling, ``catkin build`` will pass ``-jN -lN`` to ``make`` for each package. +By default ``catkin build`` on a computer with ``N`` cores will build up to ``N`` packages in parallel and will distribute ``N`` ``make`` jobs among them using an internal jobserver. +If your platform doesn't support jobserver scheduling, ``catkin build`` will pass ``-jN -lN`` to ``make`` for each package. -You can control the maximum number of packages allowed to build in parallel by -using the ``-p`` or ``--parallel-packages`` option and you can change the -number of ``make`` jobs available with the ``-j`` or ``--jobs`` option. +You can control the maximum number of packages allowed to build in parallel by using the ``-p`` or ``--parallel-packages`` option and you can change the number of ``make`` jobs available with the ``-j`` or ``--jobs`` option. -By default, these jobs options aren't passed to the underlying ``make`` -command. To disable the jobserver, you can use the ``--no-jobserver`` option, and -you can pass flags directly to ``make`` with the ``--make-args`` option. +By default, these jobs options aren't passed to the underlying ``make`` command. +To disable the jobserver, you can use the ``--no-jobserver`` option, and you can pass flags directly to ``make`` with the ``--make-args`` option. .. note:: @@ -375,25 +331,21 @@ you can pass flags directly to ``make`` with the ``--make-args`` option. Configuring Memory Use ---------------------- -In addition to CPU and load limits, ``catkin build`` can also limit the number of -running jobs based on the available memory, using the hidden ``--mem-limit`` flag. -This flag requires installing the Python ``psutil`` module and is useful on systems -without swap partitions or other situations where memory use needs to be limited. +In addition to CPU and load limits, ``catkin build`` can also limit the number of running jobs based on the available memory, using the hidden ``--mem-limit`` flag. +This flag requires installing the Python ``psutil`` module and is useful on systems without swap partitions or other situations where memory use needs to be limited. Memory is specified either by percent or by the number of bytes. -For example, to specify that ``catkin build`` should not start additional parallel jobs -when 50% of the available memory is used, you could run: +For example, to specify that ``catkin build`` should not start additional parallel jobs when 50% of the available memory is used, you could run: .. code-block:: bash - + $ catkin build --mem-limit 50% -Alternatively, if it sohuld not start additional jobs when over 4GB of memory -is used, you can specifiy: +Alternatively, if it sohuld not start additional jobs when over 4GB of memory is used, you can specifiy: .. code-block:: bash - + $ catkin build --mem-limit 4G diff --git a/docs/verbs/catkin_clean.rst b/docs/verbs/catkin_clean.rst index 3bc0d933..cc9f5fb5 100644 --- a/docs/verbs/catkin_clean.rst +++ b/docs/verbs/catkin_clean.rst @@ -1,15 +1,11 @@ ``catkin clean`` -- Clean Build Products ======================================== -The ``clean`` verb makes it easier and safer to clean various products of a catkin -workspace. In addition to removing entire **build**, **devel**, and **install spaces**, -it also gives you more fine-grained control over removing just parts of these -directories. +The ``clean`` verb makes it easier and safer to clean various products of a catkin workspace. +In addition to removing entire **build**, **devel**, and **install spaces**, it also gives you more fine-grained control over removing just parts of these directories. -The ``clean`` verb is context-aware, but in order to work, it must be given the path -to an initialized catkin workspace, or called from a path contained in an initialized -catkin workspace. This is because the paths to the relevant spaces are contained in a -workspace's metadata directory. +The ``clean`` verb is context-aware, but in order to work, it must be given the path to an initialized catkin workspace, or called from a path contained in an initialized catkin workspace. +This is because the paths to the relevant spaces are contained in a workspace's metadata directory. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/verbs/catkin_config.rst b/docs/verbs/catkin_config.rst index 59cc766f..b02631da 100644 --- a/docs/verbs/catkin_config.rst +++ b/docs/verbs/catkin_config.rst @@ -1,39 +1,30 @@ ``catkin config`` -- Configure a Workspace ========================================== -The ``config`` verb can be used to both view and mapiulate a workspace's -configuration options. These options include all of the elements listed in thr -configuration summary. +The ``config`` verb can be used to both view and mapiulate a workspace's configuration options. +These options include all of the elements listed in thr configuration summary. -By default, the ``config`` verb gets and sets options for a workspace's -*active* profile. If no profiles have been specified for a workspace, this is a -default profile named ``default``. +By default, the ``config`` verb gets and sets options for a workspace's *active* profile. +If no profiles have been specified for a workspace, this is a default profile named ``default``. .. note:: - Calling ``catkin config`` on an uninitialied workspace will not automatically - initialize it unless it is used with the ``--init`` option. + Calling ``catkin config`` on an uninitialied workspace will not automatically initialize it unless it is used with the ``--init`` option. Viewing the Configuration Summary ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Once a workspace has been initialized, the configuration summary can be -displayed by calling ``catkin config`` without arguments from anywhere under -the root of the workspace. Doing so will not modify your workspace. The -``catkin`` command is context-sensitive, so it will determine which workspace -contains the current working directory. +Once a workspace has been initialized, the configuration summary can be displayed by calling ``catkin config`` without arguments from anywhere under the root of the workspace. +Doing so will not modify your workspace. +The ``catkin`` command is context-sensitive, so it will determine which workspace contains the current working directory. Appending or Removing List-Type Arguments ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Several configuration options are actually *lists* of values. Normally for -these options, the given values will replace the current values in the -configuration. +Several configuration options are actually *lists* of values. +Normally for these options, the given values will replace the current values in the configuration. -If you would only like to modify, but not replace the value of a list-type -option, you can use the ``-a`` / ``--append-args`` and ``-r`` / -``--remove-args`` options to append or remove elements from these lists, -respectively. +If you would only like to modify, but not replace the value of a list-type option, you can use the ``-a`` / ``--append-args`` and ``-r`` / ``--remove-args`` options to append or remove elements from these lists, respectively. List-type options include: @@ -46,12 +37,9 @@ List-type options include: Installing Packages ^^^^^^^^^^^^^^^^^^^ -Without any additional arguments, packages are not "installed" using the -standard CMake ``install()`` targets. Addition of the ``--install`` option -will configure a workspace so that it creates an **install space** and write -the products of all install targets to that FHS tree. The contents of the -**install space**, which, by default, is located in a directory named -``install`` will look like the following: +Without any additional arguments, packages are not "installed" using the standard CMake ``install()`` targets. +Addition of the ``--install`` option will configure a workspace so that it creates an **install space** and write the products of all install targets to that FHS tree. +The contents of the **install space**, which, by default, is located in a directory named ``install`` will look like the following: .. code-block:: none @@ -62,27 +50,18 @@ the products of all install targets to that FHS tree. The contents of the Explicitly Specifying Workspace Chaining ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Normally, a catkin workspace automatically "extends" the other workspaces that -have previously been sourced in your environment. Each time you source a catkin -setup file from a result-space (devel-space or install-space), it sets the -``$CMAKE_PREFIX_PATH`` in your environment, and this is used to build the next -workspace. This is also sometimes referred to as "workspace chaining" and -sometimes the extended workspace is referred to as a "parent" workspace. +Normally, a catkin workspace automatically "extends" the other workspaces that have previously been sourced in your environment. +Each time you source a catkin setup file from a result-space (devel-space or install-space), it sets the ``$CMAKE_PREFIX_PATH`` in your environment, and this is used to build the next workspace. +This is also sometimes referred to as "workspace chaining" and sometimes the extended workspace is referred to as a "parent" workspace. -With ``catkin config``, you can explicitly set the workspace you want to extend, -using the ``--extend`` argument. This is equivalent to sourcing a setup file, -building, and then reverting to the environment before sourcing the setup file. +With ``catkin config``, you can explicitly set the workspace you want to extend, using the ``--extend`` argument. +This is equivalent to sourcing a setup file, building, and then reverting to the environment before sourcing the setup file. -Note that in case the desired parent workspace is different from one already -being used, using the ``--extend`` argument also necessitates cleaning the -setup files from your workspace with ``catkin clean``. +Note that in case the desired parent workspace is different from one already being used, using the ``--extend`` argument also necessitates cleaning the setup files from your workspace with ``catkin clean``. -For example, regardless of your current environment variable settings (like -``$CMAKE_PREFIX_PATH``), this will build your workspace against the -``/opt/ros/hydro`` install space. +For example, regardless of your current environment variable settings (like ``$CMAKE_PREFIX_PATH``), this will build your workspace against the ``/opt/ros/hydro`` install space. -First start with an empty ``CMAKE_PREFIX_PATH`` and initialize, build, and -source a workspace: +First start with an empty ``CMAKE_PREFIX_PATH`` and initialize, build, and source a workspace: .. code-block:: bash @@ -121,10 +100,10 @@ source a workspace: Workspace configuration appears valid. -------------------------------------------------------------- -At this point you have a workspace which doesn't extend anything. If you -realize this after the fact, you can explicitly tell it to extend another -workspace. Suppose you wanted to extend a standard ROS system install like -``/opt/ros/hydro``. This can be done with the ``--extend`` option: +At this point you have a workspace which doesn't extend anything. +If you realize this after the fact, you can explicitly tell it to extend another workspace. +Suppose you wanted to extend a standard ROS system install like ``/opt/ros/hydro``. +This can be done with the ``--extend`` option: .. code-block:: bash @@ -166,12 +145,9 @@ workspace. Suppose you wanted to extend a standard ROS system install like Whitelisting and Blacklisting Packages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Packages can be added to a package *whitelist* or *blacklist* in order to -change which packages get built. If the *whitelist* is non-empty, then a call -to ``catkin build`` with no specific package names will only build the packages -on the *whitelist*. This means that you can still build packages not on the -*whitelist*, but only if they are named explicitly or are dependencies of other -whitelisted packages. +Packages can be added to a package *whitelist* or *blacklist* in order to change which packages get built. +If the *whitelist* is non-empty, then a call to ``catkin build`` with no specific package names will only build the packages on the *whitelist*. +This means that you can still build packages not on the *whitelist*, but only if they are named explicitly or are dependencies of other whitelisted packages. To set the whitelist, you can call the following command: @@ -185,9 +161,8 @@ To clear the whitelist, you can use the ``--no-whitelist`` option: catkin config --no-whitelist -If the *blacklist* is non-empty, it will filter the packages to be built in all -cases except where a given package is named explicitly. This means that blacklisted -packages will not be built even if another package in the workspace depends on them. +If the *blacklist* is non-empty, it will filter the packages to be built in all cases except where a given package is named explicitly. +This means that blacklisted packages will not be built even if another package in the workspace depends on them. .. note:: @@ -206,18 +181,14 @@ To clear the blacklist, you can use the ``--no-blacklist`` option: catkin config --no-blacklist -Note that you can still build packages on the blacklist and whitelist by -passing their names to ``catkin build`` explicitly. +Note that you can still build packages on the blacklist and whitelist by passing their names to ``catkin build`` explicitly. Accelerated Building with Environment Caching ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Each package is built in a special environment which is loaded from the -current workspace and any workspaces that the current workspace is extending. -If you are confident that your workspace's environment is not changing during -a build, you can tell ``catkin build`` to cache these environments with the -``--cache-env`` option. This has the effect of dramatically reducing build times -for workspaces where many packages are already built. +Each package is built in a special environment which is loaded from the current workspace and any workspaces that the current workspace is extending. +If you are confident that your workspace's environment is not changing during a build, you can tell ``catkin build`` to cache these environments with the ``--cache-env`` option. +This has the effect of dramatically reducing build times for workspaces where many packages are already built. Full Command-Line Interface diff --git a/docs/verbs/catkin_env.rst b/docs/verbs/catkin_env.rst index 7ab99a86..21d49f89 100644 --- a/docs/verbs/catkin_env.rst +++ b/docs/verbs/catkin_env.rst @@ -1,11 +1,9 @@ ``catkin env`` -- Environment Utility ===================================== -The ``env`` verb can be used to both print the current environment variables -and run a command in a modified environment. This verb is supplied as a -cross-platform alternative to the UNIX ``env`` command or the ``cmake -E -environment`` command. It is primarily used in the build stage command -reproduction. +The ``env`` verb can be used to both print the current environment variables and run a command in a modified environment. +This verb is supplied as a cross-platform alternative to the UNIX ``env`` command or the ``cmake -E environment`` command. +It is primarily used in the build stage command reproduction. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/verbs/catkin_init.rst b/docs/verbs/catkin_init.rst index ce1b766b..477dcefb 100644 --- a/docs/verbs/catkin_init.rst +++ b/docs/verbs/catkin_init.rst @@ -1,20 +1,14 @@ ``catkin init`` -- Initialize a Workspace ========================================= -The ``init`` verb is the simplest way to "initialize" a catkin workspace so that -it can be automatically detected automatically by other verbs which need to know -the location of the workspace root. +The ``init`` verb is the simplest way to "initialize" a catkin workspace so that it can be automatically detected automatically by other verbs which need to know the location of the workspace root. -This verb does not store any configuration information, but simply creates the -hidden ``.catkin_tools`` directory in the specified workspace. If you want to -initialize a workspace simultaneously with an initial config, see the -``--init`` option for the ``config`` verb. +This verb does not store any configuration information, but simply creates the hidden ``.catkin_tools`` directory in the specified workspace. +If you want to initialize a workspace simultaneously with an initial config, see the ``--init`` option for the ``config`` verb. -Catkin workspaces can be initialized anywhere. The only constraint is that -catkin workspaces cannot contain other catkin workspaces. If you call ``caktin -init`` and it reports an error saying that the given directory is already -contained in a workspace, you can call ``catkin config`` to determine the root -of that workspace. +Catkin workspaces can be initialized anywhere. +The only constraint is that catkin workspaces cannot contain other catkin workspaces. +If you call ``caktin init`` and it reports an error saying that the given directory is already contained in a workspace, you can call ``catkin config`` to determine the root of that workspace. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/verbs/catkin_list.rst b/docs/verbs/catkin_list.rst index 730d7121..0726157e 100644 --- a/docs/verbs/catkin_list.rst +++ b/docs/verbs/catkin_list.rst @@ -1,23 +1,20 @@ ``catkin list`` -- List Package Info ==================================== -The ``list`` verb for the ``catkin`` command is used to find and list -information about catkin packages. By default, it will list the packages in the -workspace containing the current working directoy. It can also be used to list -the packages in any other arbitrary directory. +The ``list`` verb for the ``catkin`` command is used to find and list information about catkin packages. +By default, it will list the packages in the workspace containing the current working directoy. +It can also be used to list the packages in any other arbitrary directory. Checking for Catkin Package Warnings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In addition to the names of the packages in your workspace, running ``catkin -list`` will output any warnings about catkin packages in your workspace. To -suppress these warnings, you can use the ``--quiet`` option. +In addition to the names of the packages in your workspace, running ``catkin list`` will output any warnings about catkin packages in your workspace. +To suppress these warnings, you can use the ``--quiet`` option. Using Unformatted Output in Shell Scripts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``catkin list --unformatted`` is useful for automating shell scripts in UNIX -pipe-based programs. +``catkin list --unformatted`` is useful for automating shell scripts in UNIX pipe-based programs. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/verbs/catkin_locate.rst b/docs/verbs/catkin_locate.rst index f4993c35..2ea31396 100644 --- a/docs/verbs/catkin_locate.rst +++ b/docs/verbs/catkin_locate.rst @@ -1,9 +1,7 @@ ``catkin locate`` -- Locate Directories ======================================= -The ``locate`` verb can be used to locate important locations in the workspace such as -the active ``source``, ``build``, ``devel``, and ``install`` spaces, and package -directories in the workspace. +The ``locate`` verb can be used to locate important locations in the workspace such as the active ``source``, ``build``, ``devel``, and ``install`` spaces, and package directories in the workspace. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/verbs/catkin_profile.rst b/docs/verbs/catkin_profile.rst index 386d53cb..b7c863b5 100644 --- a/docs/verbs/catkin_profile.rst +++ b/docs/verbs/catkin_profile.rst @@ -1,17 +1,13 @@ ``catkin profile`` -- Manage Profiles ===================================== -Many verbs contain a ``--profile`` option, which selects which configuration -profile to use, without which it will use the "active" profile. The ``profile`` -verb enables you to manager the available profiles as well as set the "active" -profile when using other verbs. +Many verbs contain a ``--profile`` option, which selects which configuration profile to use, without which it will use the "active" profile. +The ``profile`` verb enables you to manager the available profiles as well as set the "active" profile when using other verbs. -Even without using the ``profile`` verb, any use of the ``catkin`` command -which changes the workspace is impliclty using a configuration profile called -"default". +Even without using the ``profile`` verb, any use of the ``catkin`` command which changes the workspace is impliclty using a configuration profile called ``default``. -The ``profile`` verb has several sub-commands for profile management. These include -the following: +The ``profile`` verb has several sub-commands for profile management. +These include the following: - ``list`` -- List the available profiles - ``set`` -- Set the active profile by name. @@ -23,8 +19,7 @@ Creating Profiles Automatically ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After initializing a workspace, you can start querying information about profiles. -Until you execute a verb which actually writes a profile configuration, however, -there will be no profiles listed: +Until you execute a verb which actually writes a profile configuration, however, there will be no profiles listed: .. code-block:: bash @@ -35,8 +30,7 @@ there will be no profiles listed: [profile] This workspace has no metadata profiles. Any configuration settings will automatically by applied to a new profile called `default`. -To see these effects, you can run ``catkin config`` to write a default -configuration to the workspace: +To see these effects, you can run ``catkin config`` to write a default configuration to the workspace: .. code-block:: bash @@ -66,10 +60,8 @@ configuration to the workspace: [profile] Available profiles: - default (active) -The ``profile`` verb now shows that the profile named "default" is avialable -and is active. Calling ``catkin config`` with the ``--profile`` argument -will automatically create a profile based on the given configuration -options: +The ``profile`` verb now shows that the profile named "default" is avialable and is active. +Calling ``catkin config`` with the ``--profile`` argument will automatically create a profile based on the given configuration options: .. code-block:: bash @@ -99,16 +91,13 @@ options: - alternate - default (active) -Note that while the profile named ``alternate`` has been configured, it is -still not *active*, so any calls to catkin-verbs without an explicit -``--profile alternate`` option will still use the profile named ``default``. +Note that while the profile named ``alternate`` has been configured, it is still not *active*, so any calls to catkin-verbs without an explicit ``--profile alternate`` option will still use the profile named ``default``. Explicitly Creating Profiles ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Profiles can also be added explicitly with the ``add`` command. This profile can -be initialized with configuration information from either the default settings or -another profile. +Profiles can also be added explicitly with the ``add`` command. +This profile can be initialized with configuration information from either the default settings or another profile. .. code-block:: bash @@ -126,8 +115,8 @@ another profile. Setting the Active Profile ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The active profile can be easily set with the ``set`` sub-command. Suppose -a workspace has the following profiles: +The active profile can be easily set with the ``set`` sub-command. +Suppose a workspace has the following profiles: .. code-block:: bash diff --git a/docs/verbs/cli/catkin_clean.txt b/docs/verbs/cli/catkin_clean.txt index c8d72f66..feffc45e 100644 --- a/docs/verbs/cli/catkin_clean.txt +++ b/docs/verbs/cli/catkin_clean.txt @@ -1,5 +1,8 @@ -usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE] [-a] [-b] - [-d] [-i] [-c] [-s] [-o] +usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE] + [--dry-run] [--verbose] [--yes] [--force] [--all-profiles] + [--deinit] [-l] [-b] [-d] [-i] [--dependants] [--orphans] + [--setup-files] + [PKGNAME [PKGNAME ...]] Deletes various products of the build verb. @@ -10,26 +13,46 @@ optional arguments: contained within it (default: ".") --profile PROFILE The name of a config profile to use (default: active profile) + --dry-run, -n Show the effects of the clean action without modifying + the workspace. + --verbose, -v Verbose status output. + --yes, -y Assume "yes" to all interactive checks. + --force, -f Allow cleaning files outside of the workspace root. + --all-profiles Apply the specified clean operation for all profiles + in this workspace. -Basic: - Clean workspace subdirectories. +Full: + Remove everything except the source space. - -a, --all Remove all of the *spaces associated with the given or - active profile. This will remove everything but the - source space and the hidden .catkin_tools directory. - -b, --build Remove the buildspace. - -d, --devel Remove the develspace. - -i, --install Remove the installspace. + --deinit De-initialize the workspace, delete all build profiles + and configuration. This will also clean subdirectories + for all profiles in the workspace. -Advanced: - Clean only specific parts of the workspace. These options will - automatically enable the --force-cmake option for the next build +Spaces: + Clean workspace subdirectories for the selected profile. + + -l, --logs Remove the entire log space. + -b, --build Remove the entire build space. + -d, --devel Remove the entire devel space. + -i, --install Remove the entire install space. + +Packages: + Clean products from specific packages in the workspace. Note that these + options are only available in a `linked` devel space layout. These options + will also automatically enable the --force-cmake option for the next build invocation. - -c, --cmake-cache Clear the CMakeCache for each package, but leave build - and devel spaces. - -s, --setup-files Clear the catkin-generated files in order to rebase - onto another workspace. - -o, --orphans Remove only build directories whose source packages - are no longer enabled or in the source space. This - might require --force-cmake on the next build. + PKGNAME Explicilty specify a list of specific packages to + clean from the build, devel, and install space. + --dependants, --deps Clean the packages which depend on the packages to be + cleaned. + --orphans Remove products from packages are no longer in the + source space. Note that this also removes packages + which are blacklisted or which contain `CATKIN_INGORE` + marker files. + +Advanced: + Clean other specific parts of the workspace. + + --setup-files Clear the catkin-generated setup files from the devel + and install spaces. diff --git a/docs/verbs/cli/catkin_config.txt b/docs/verbs/cli/catkin_config.txt index 16df57b9..b9eff585 100644 --- a/docs/verbs/cli/catkin_config.txt +++ b/docs/verbs/cli/catkin_config.txt @@ -4,11 +4,12 @@ usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE] [--whitelist PKG [PKG ...] | --no-whitelist] [--blacklist PKG [PKG ...] | --no-blacklist] [-s SOURCE_SPACE | --default-source-space] + [-l LOG_SPACE | --default-log-space] [-b BUILD_SPACE | --default-build-space] [-d DEVEL_SPACE | --default-devel-space] [-i INSTALL_SPACE | --default-install-space] [-x SPACE_SUFFIX] - [--merge-devel | --link-devel | --isolate-devel] + [--link-devel | --merge-devel | --isolate-devel] [--install | --no-install] [--isolate-install | --merge-install] [-j JOBS] [-p PACKAGE_JOBS] [--jobserver | --no-jobserver] @@ -70,6 +71,9 @@ Spaces: The path to the source space. --default-source-space Use the default path to the source space ("src") + -l LOG_SPACE, --log-space LOG_SPACE + The path to the log space. + --default-log-space Use the default path to the log space ("logs") -b BUILD_SPACE, --build-space BUILD_SPACE The path to the build space. --default-build-space @@ -89,11 +93,11 @@ Spaces: Devel Space: Options for configuring the structure of the devel space. - --merge-devel Build products from each catkin package into a single - merged devel spaces. --link-devel Build products from each catkin package into isolated spaces, then symbolically link them into a merged devel space. + --merge-devel Build products from each catkin package into a single + merged devel spaces. --isolate-devel Build products from each catkin package into isolated devel spaces. diff --git a/docs/verbs/cli/catkin_create_pkg.txt b/docs/verbs/cli/catkin_create_pkg.txt index 94cd79fc..fff15ebf 100644 --- a/docs/verbs/cli/catkin_create_pkg.txt +++ b/docs/verbs/cli/catkin_create_pkg.txt @@ -1,4 +1,4 @@ -usage: catkin create pkg [-h] [-p PATH] [--rosdistro ROSDISTRO] +usage: catkin create pkg [-h] [-p PATH] --rosdistro ROSDISTRO [-v MAJOR.MINOR.PATCH] [-l LICENSE] [-m NAME EMAIL] [-a NAME EMAIL] [-d DESCRIPTION] [--catkin-deps [DEP [DEP ...]]] diff --git a/docs/verbs/cli/catkin_list.txt b/docs/verbs/cli/catkin_list.txt index f6206e7b..93f00a2f 100644 --- a/docs/verbs/cli/catkin_list.txt +++ b/docs/verbs/cli/catkin_list.txt @@ -1,14 +1,10 @@ -usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE] [--deps] - [--depends-on [DEPENDS_ON [DEPENDS_ON ...]]] [--quiet] +usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE] + [--deps | --rdeps] [--depends-on [PKG [PKG ...]]] + [--rdepends-on [PKG [PKG ...]]] [--this] [--quiet] [--unformatted] - [folders [folders ...]] Lists catkin packages in the workspace or other arbitray folders. -positional arguments: - folders Folders in which to find packages. (default: workspace - source space) - optional arguments: -h, --help show this help message and exit --workspace WORKSPACE, -w WORKSPACE @@ -16,10 +12,29 @@ optional arguments: contained within it (default: ".") --profile PROFILE The name of a config profile to use (default: active profile) + +Information: + Control which information is shown. + --deps, --dependencies - List dependencies of each package. - --depends-on [DEPENDS_ON [DEPENDS_ON ...]] - List all packages that depend on supplied argument + Show direct dependencies of each package. + --rdeps, --recursive-dependencies + Show recursive dependencies of each package. + +Packages: + Control which packages are listed. + + --depends-on [PKG [PKG ...]] + Only show packages that directly depend on specific + package(s). + --rdepends-on [PKG [PKG ...]], --recursive-depends-on [PKG [PKG ...]] + Only show packages that recursively depend on specific package(s). + --this Show the package which contains the current working + directory. + +Interface: + The behavior of the command-line interface. + --quiet Don't print out detected package warnings. --unformatted, -u Print list without punctuation and additional details. diff --git a/docs/verbs/cli/catkin_locate.txt b/docs/verbs/cli/catkin_locate.txt index 4c2de904..a03acab9 100644 --- a/docs/verbs/cli/catkin_locate.txt +++ b/docs/verbs/cli/catkin_locate.txt @@ -1,5 +1,5 @@ usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e] - [-r] [-s | -b | -d | -i] + [-r] [-q] [-s | -b | -d | -i] [PACKAGE] Get the paths to various locations in a workspace. @@ -15,6 +15,7 @@ optional arguments: Behavior: -e, --existing-only Only print paths to existing directories. -r, --relative Print relative paths instead of the absolute paths. + -q, --quiet Suppress warning output. Sub-Space Options: Get the absolute path to one of the following locations in the given From 878f48d7e3cafa5d40b8d31d5bb9cd19db6ee841 Mon Sep 17 00:00:00 2001 From: Jonathan Bohren Date: Wed, 13 Apr 2016 18:37:46 -0400 Subject: [PATCH 07/10] docs: updating after merging #293 - regenerating examples and cli interfaces - switching all text to sentence-per-line - adding scripts and documentation for regenerating examples - moving --locate-extra-shell-verbs to locate verb - adding details on linked develspace --- catkin_tools/commands/catkin.py | 10 -- catkin_tools/verbs/catkin_locate/cli.py | 20 +++ docs/advanced/linked_develspace.rst | 20 +++ docs/build_types.rst | 2 - docs/cheat_sheet.rst | 6 +- docs/config_summary.rst | 145 ------------------ docs/examples/README.md | 45 ++++++ docs/examples/capture | 5 - docs/examples/failure_ws/all.bash | 15 ++ .../quickstart_ws/1_prebuild.bash.out | 11 -- docs/examples/quickstart_ws/1_prebuild.out | 13 ++ .../quickstart_ws/2_postbuild.bash.out | 31 ---- docs/examples/quickstart_ws/2_postbuild.out | 41 +++++ docs/examples/quickstart_ws/all.bash | 16 ++ docs/examples/ros_tutorials_ws/all.bash | 23 +++ docs/history.rst | 1 + docs/index.rst | 3 +- docs/mechanics.rst | 58 +++---- docs/quick_start.rst | 8 +- docs/verbs/catkin_build.rst | 18 +-- docs/verbs/catkin_clean.rst | 96 +++++++++++- docs/verbs/cli/catkin_locate.txt | 9 +- 22 files changed, 345 insertions(+), 251 deletions(-) create mode 100644 docs/advanced/linked_develspace.rst delete mode 100644 docs/config_summary.rst create mode 100644 docs/examples/README.md delete mode 100755 docs/examples/capture create mode 100755 docs/examples/failure_ws/all.bash delete mode 100644 docs/examples/quickstart_ws/1_prebuild.bash.out create mode 100644 docs/examples/quickstart_ws/1_prebuild.out delete mode 100644 docs/examples/quickstart_ws/2_postbuild.bash.out create mode 100644 docs/examples/quickstart_ws/2_postbuild.out create mode 100755 docs/examples/quickstart_ws/all.bash create mode 100755 docs/examples/ros_tutorials_ws/all.bash diff --git a/catkin_tools/commands/catkin.py b/catkin_tools/commands/catkin.py index a3fb8034..c09ea4aa 100644 --- a/catkin_tools/commands/catkin.py +++ b/catkin_tools/commands/catkin.py @@ -155,8 +155,6 @@ def catkin_main(sysargs): help='Forces catkin to output in color, even when the terminal does not appear to support it.') add('--no-color', action='store_true', default=False, help='Forces catkin to not use color in the output, regardless of the detect terminal type.') - add('--locate-extra-shell-verbs', action='store_true', - help='Returns the full path of the file to source for extra shell verbs, then exits.') # Generate a list of verbs available verbs = list_verbs() @@ -211,14 +209,6 @@ def catkin_main(sysargs): # Do verb alias expansion sysargs = expand_verb_aliases(sysargs, verb_aliases) - # Check for --locate-extra-shell-verbs - for arg in sysargs: - if arg == '--locate-extra-shell-verbs': - this_dir = os.path.dirname(__file__) - shell_verbs = os.path.join(this_dir, '..', 'verbs', 'catkin_shell_verbs.bash') - print(os.path.normpath(shell_verbs)) - sys.exit(0) - # Determine the verb, splitting arguments into pre and post verb verb = None pre_verb_args = [] diff --git a/catkin_tools/verbs/catkin_locate/cli.py b/catkin_tools/verbs/catkin_locate/cli.py index da5ba961..d9a3b67a 100644 --- a/catkin_tools/verbs/catkin_locate/cli.py +++ b/catkin_tools/verbs/catkin_locate/cli.py @@ -72,6 +72,15 @@ def prepare_arguments(parser): add('package', metavar='PACKAGE', nargs='?', help="The name of a package to locate.") + special_group = parser.add_argument_group( + 'Special Directories', + 'Get the absolute path to a special catkin location') + add = special_group.add_argument + add('--shell-verbs', action='store_true', + help="Get the path to the shell verbs script.") + add('--examples', action='store_true', + help="Get the path to the examples directory.") + return parser @@ -79,6 +88,17 @@ def main(opts): # Initialize dictionary version of opts namespace opts_vars = vars(opts) if opts else {} + # Check for special locations + root_resource_path = os.path.join(os.path.dirname(__file__), '..', '..') + if opts.shell_verbs: + shell_verbs = os.path.join(root_resource_path, 'verbs', 'catkin_shell_verbs.bash') + print(os.path.normpath(shell_verbs)) + sys.exit(0) + elif opts.examples: + shell_verbs = os.path.join(root_resource_path, '..', 'docs', 'examples') + print(os.path.normpath(shell_verbs)) + sys.exit(0) + # Get the workspace (either the given directory or the enclosing ws) workspace_hint = opts_vars.get('workspace', None) or os.getcwd() workspace = find_enclosing_workspace(workspace_hint) diff --git a/docs/advanced/linked_develspace.rst b/docs/advanced/linked_develspace.rst new file mode 100644 index 00000000..59b46cd3 --- /dev/null +++ b/docs/advanced/linked_develspace.rst @@ -0,0 +1,20 @@ +Linked Devel Space +================== + +In addition to the ``merged`` and ``isolated`` **devel space** layouts provided by ``catkin_make`` and ``catkin_make_isolated``, respectively, ``catkin_tools`` provides a default ``linked`` layout which enables robust cleaning of individual packages from a workspace. +It does this by building each package into its own hidden FHS tree, and then symbolically linking all products into the unified **devel space** which is specified in the workspace configuration. + +When building with a ``linked`` layout, Catkin packages are built into FHS trees stored in the ``.private`` hidden directory at the root of the **devel space**. +Within this directory is a directory for each package in the workspace. + +Setup File Generation +^^^^^^^^^^^^^^^^^^^^^ + +In the ``merged`` layout, every package writes and then over-writes the colliding setup files in the root of the **devel space**. +This leads to race conditions and other problems when trying to parallelize building. +With he ``linked`` layout, however, only one package generates these files, and this is either a built-in "prebuild" package, or if it exists in the workspace, the ``catkin`` CMake package, itself. + +.catkin File Generation +^^^^^^^^^^^^^^^^^^^^^^^ + +When using the ``linked`` layout, ``catkin_tools`` is also responsible for managing the ``.catkin`` file in the root of the **devel space**. diff --git a/docs/build_types.rst b/docs/build_types.rst index f0fe2915..1fce041c 100644 --- a/docs/build_types.rst +++ b/docs/build_types.rst @@ -67,8 +67,6 @@ Build Stages First Subsequent Description ============== ============ ================================================== ``mkdir`` | Create package build space if it doesn't exist. ----------------------------- -------------------------------------------------- - ``envgen`` | Generate environment setup file for building. ---------------------------- -------------------------------------------------- ``cmake`` ``check`` | Run CMake configure step **once** for the | first build and the ``cmake_check_build_system`` diff --git a/docs/cheat_sheet.rst b/docs/cheat_sheet.rst index 1d8461e1..69dfe513 100644 --- a/docs/cheat_sheet.rst +++ b/docs/cheat_sheet.rst @@ -80,13 +80,13 @@ Cleaning Build Products ^^^^^^^^^^^^^^^^^^^^^^^ Blow away the build, devel, and install spaces (if they exist): - - ``catkin clean -a`` + - ``catkin clean`` ... or just the **build space**: - ``catkin clean --build`` -... or just delete the `CMakeCache.txt` files for each package: - - ``catkin clean --cmake-cache`` +... or just clean a single package: + - ``catkin clean PKGNAME`` ... or just delete the build directories for packages which have been disabled or removed: - ``catkin clean --orphans`` diff --git a/docs/config_summary.rst b/docs/config_summary.rst deleted file mode 100644 index 83edc2a1..00000000 --- a/docs/config_summary.rst +++ /dev/null @@ -1,145 +0,0 @@ -Configuration Summary -===================== - -Contents of the Config Summary -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Most ``catkin`` commands which modify a workspace's configuration will display the standard configuration summary, as shown below: - -.. code-block:: bash - - $ cd /tmp/path/to/my_catkin_ws - $ catkin config - -------------------------------------------------------------- - Profile: default - Extending: None - Workspace: /tmp/path/to/my_catkin_ws - Source Space: [exists] /tmp/path/to/my_catkin_ws/src - Build Space: [missing] /tmp/path/to/my_catkin_ws/build - Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel - Install Space: [missing] /tmp/path/to/my_catkin_ws/install - DESTDIR: None - -------------------------------------------------------------- - Isolate Develspaces: False - Install Packages: False - Isolate Installs: False - -------------------------------------------------------------- - Additional CMake Args: None - Additional Make Args: None - Additional catkin Make Args: None - -------------------------------------------------------------- - Whitelisted Packages: None - Blacklisted Packages: None - -------------------------------------------------------------- - Workspace configuration appears valid. - -------------------------------------------------------------- - -This summary describes the layout of the workspace as well as other important settings which influence build and execution behavior. -Each of these options can be modified either with the ``config`` verb's options described in the full command-line usage or by changing environment variables. -The summary is composed of the following sections: - -Overview Section ----------------- - -- **Profile** -- The name of this configuration -- **Extending** -- Describes if your current configuration will extend another Catkin workspace, and through which mechanism it determined the location of the extended workspace: - - - *No Chaining* - - .. code-block:: bash - - Extending: None - - - *Implicit Chaining* -- Derived from the ``CMAKE_PREFIX_PATH`` environment or cache variable. - - .. code-block:: bash - - Extending: [env] /opt/ros/hydro - .. code-block:: bash - - Extending: [cached] /opt/ros/hydro - - - *Explicit Chaining* -- Specified by ``catkin config --extend`` - - .. code-block:: bash - - Extending: [explicit] /opt/ros/hydro - -- **[* Space]** -- Lists the paths to each of the catkin "spaces" and whether or not they exist -- **DESTDIR** -- An optional prefix to the **install space** as defined by `GNU Standards `_ -- **Isolate Develspaces** -- Builds products (like libraries and binaries) into individual FHS subdirectories in the **devel space**, instead of a single FHS directory -- **Install Packages** -- Enable creating and installation into the **install space** -- **Isolate Installs** -- Installs products into individual FHS subdirectories in the **install space** -- **Additional CMake Args** -- Arguments to be passed to CMake during the *configuration* step for all packages to be built. -- **Additional Make Args** -- Arguments to be passed to Make during the *build* step for all packages to be built. -- **Additional catkin Make Args** -- Similar to **Additional Make Args** but only applies to Catkin packages. -- **Package Whitelist** -- These are the packages that will be built with a bare call to ``catkin build`` -- **Package Blacklist** -- These are the packages that will *not* be built unless explicitly named - -Notes Section -------------- - -The summary will sometimes contain notes about the workspace or the action that -you're performing, or simply tell you that the workspace configuration appears -valid. - -Warnings Section ----------------- - -If something is wrong with your configuration such as a missing source space, -an additional section will appear at the bottom of the summary with details on -what is wrong and how you can fix it. - -Workspace Chaining Mode -^^^^^^^^^^^^^^^^^^^^^^^ - -An important property listed in the configuration configuration which deserves attention is the summary value of the ``Extending`` property. -This affects which other collections of libraries and packages which will be visible to your workspace. -This is process called "workspace chaining." For more details on this see the details about workspace chaining and ``CMAKE_PREFIX_PATH`` in :doc:`Workspace Mechanics `. - -The information about which workspace to extend can come from a few different sources, and can be classified in one of three ways: - -No Chaining ------------ - -This is what is shown in the above example configuration and it implies that there are no other Catkin workspaces which this workspace extends. -The user has neither explicitly specified a workspace to extend, and the ``CMAKE_PREFIX_PATH`` environment variable is empty: - -.. code-block:: bash - - Extending: None - -Implicit Chaining via ``CMAKE_PREFIX_PATH`` Environment or Cache Variable -------------------------------------------------------------------------- - -In this case, the ``catkin`` command is *implicitly* assuming that you want to build this workspace against resources which have been built into the directories listed in your ``CMAKE_PREFIX_PATH`` environment variable. -As such, you can control this value simply by changing this environment variable. - -For example, ROS users who load their system's installed ROS environment by calling something similar to ``source /opt/ros/hydro/setup.bash`` will normally see an ``Extending`` value such as: - -.. code-block:: bash - - Extending: [env] /opt/ros/hydro - -If you don't want to extend the given workspace, unsetting the ``CMAKE_PREFIX_PATH`` environment variable will change it back to none. - -Once you have built your workspace once, this ``CMAKE_PREFIX_PATH`` will be cached by the underlying CMake buildsystem. -As such, the ``Extending`` status will subsequently describe this as the "cached" extension path: - -.. code-block:: bash - - Extending: [cached] /opt/ros/hydro - -Once the extension mode is cached like this, you must use ``catkin clean`` to before changing it to something else. - -Explicit Chaining via ``catkin config --extend`` ------------------------------------------------- - -This behaves like the above implicit chaining except it means that this workspace is *explicitly* extending another workspace and the workspaces which the other workspace extends, recursively. -This can be set with the ``catkin config --extend`` command. -It will override the value of ``CMAKE_PREFIX_PATH`` and persist between builds. - -.. code-block:: bash - - Extending: [explicit] /tmp/path/to/other_ws - diff --git a/docs/examples/README.md b/docs/examples/README.md new file mode 100644 index 00000000..1c00d0fd --- /dev/null +++ b/docs/examples/README.md @@ -0,0 +1,45 @@ +Documentation Examples +====================== + +This document explains how to run examples and generate all static text and +asciinema videos. + +## Prerequisites + +* [perl](http://perl.org) +* [asciinema](http://asciinema.org) +* [rosinstall\_generator](https://github.com/vcstools/wstool) +* [wstool](https://github.com/vcstools/wstool) +* [catkin](https://github.com/ros/catkin) + +## Generating All Examples + +All examples must be run from the examples directory. + +```bash +./quickstart_ws/all.bash +./failure_ws/all.bash +./ros_tutorials_ws/all.bash +``` + +## Scripts + +### slowrun + +The `slowrun` script executes a script line by line, echoing characters to the +console with a delay, as if they were being typed. + +Optional arguments: + +* `--buffer` -- buffer and delay printing of each line from the output from subcommands + +### slowrecord + +The `slowrecord` script executes a script line by line with `slowrun`, but also +spawns a `urxvt` terminal with a specific size, and records the commands with +`asciinema`. + +Optional arguments: + +* `--check` -- check interactively before uploading +* `--tall` -- use a taller window for recording diff --git a/docs/examples/capture b/docs/examples/capture deleted file mode 100755 index b04a1b77..00000000 --- a/docs/examples/capture +++ /dev/null @@ -1,5 +0,0 @@ -#!/usr/bin/env bash - -# Simple script to run another script and capture the output - -. $1 > "$1.out" diff --git a/docs/examples/failure_ws/all.bash b/docs/examples/failure_ws/all.bash new file mode 100755 index 00000000..98bd11f3 --- /dev/null +++ b/docs/examples/failure_ws/all.bash @@ -0,0 +1,15 @@ +#!/usr/bin/env bash + +SLOWRECORD=$(pwd)/slowrecord +WS=/tmp/failure_ws + +pushd `dirname $0` + +rm -rf $WS + +source /opt/ros/indigo/setup.bash +bash 0_init.bash +$SLOWRECORD --check --tall --buffer 1_build_warning.bash +$SLOWRECORD --check --tall --buffer 2_build_err.bash + +popd diff --git a/docs/examples/quickstart_ws/1_prebuild.bash.out b/docs/examples/quickstart_ws/1_prebuild.bash.out deleted file mode 100644 index ef250550..00000000 --- a/docs/examples/quickstart_ws/1_prebuild.bash.out +++ /dev/null @@ -1,11 +0,0 @@ -. -├── .catkin_tools -│   ├── default -│   └── README -└── src - ├── pkg_a - ├── pkg_b - ├── pkg_c - └── pkg_d - -7 directories, 1 file diff --git a/docs/examples/quickstart_ws/1_prebuild.out b/docs/examples/quickstart_ws/1_prebuild.out new file mode 100644 index 00000000..831a0284 --- /dev/null +++ b/docs/examples/quickstart_ws/1_prebuild.out @@ -0,0 +1,13 @@ +. +├── .catkin_tools +│   ├── CATKIN_IGNORE +│   ├── profiles +│   ├── README +│   └── VERSION +└── src + ├── pkg_a + ├── pkg_b + ├── pkg_c + └── pkg_d + +7 directories, 3 files diff --git a/docs/examples/quickstart_ws/2_postbuild.bash.out b/docs/examples/quickstart_ws/2_postbuild.bash.out deleted file mode 100644 index f982efc2..00000000 --- a/docs/examples/quickstart_ws/2_postbuild.bash.out +++ /dev/null @@ -1,31 +0,0 @@ -. -├── build -│   ├── .built_by -│   ├── .catkin_tools.yaml -│   ├── _logs -│   ├── pkg_a -│   ├── pkg_b -│   ├── pkg_c -│   └── pkg_d -├── .catkin_tools -│   ├── default -│   └── README -├── devel -│   ├── .built_by -│   ├── .catkin -│   ├── env.sh -│   ├── etc -│   ├── lib -│   ├── .rosinstall -│   ├── setup.bash -│   ├── setup.sh -│   ├── _setup_util.py -│   ├── setup.zsh -│   └── share -└── src - ├── pkg_a - ├── pkg_b - ├── pkg_c - └── pkg_d - -17 directories, 11 files diff --git a/docs/examples/quickstart_ws/2_postbuild.out b/docs/examples/quickstart_ws/2_postbuild.out new file mode 100644 index 00000000..4c116696 --- /dev/null +++ b/docs/examples/quickstart_ws/2_postbuild.out @@ -0,0 +1,41 @@ +. +├── build +│   ├── .built_by +│   ├── catkin_tools_prebuild +│   ├── .catkin_tools.yaml +│   ├── pkg_a +│   ├── pkg_b +│   ├── pkg_c +│   └── pkg_d +├── .catkin_tools +│   ├── CATKIN_IGNORE +│   ├── profiles +│   ├── README +│   └── VERSION +├── devel +│   ├── .built_by +│   ├── .catkin +│   ├── CMakeLists.txt -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/CMakeLists.txt +│   ├── env.sh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/env.sh +│   ├── etc +│   ├── lib +│   ├── package.xml -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/package.xml +│   ├── .private +│   ├── setup.bash -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.bash +│   ├── setup.sh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.sh +│   ├── _setup_util.py -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/_setup_util.py +│   ├── setup.zsh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.zsh +│   └── share +├── logs +│   ├── catkin_tools_prebuild +│   ├── pkg_a +│   ├── pkg_b +│   ├── pkg_c +│   └── pkg_d +└── src + ├── pkg_a + ├── pkg_b + ├── pkg_c + └── pkg_d + +24 directories, 14 files diff --git a/docs/examples/quickstart_ws/all.bash b/docs/examples/quickstart_ws/all.bash new file mode 100755 index 00000000..49e11a46 --- /dev/null +++ b/docs/examples/quickstart_ws/all.bash @@ -0,0 +1,16 @@ +#!/usr/bin/env bash + +SLOWRECORD=$(pwd)/slowrecord +WS=/tmp/quickstart_ws + +pushd `dirname $0` + +rm -rf $WS +bash 0_quickstart.bash +pushd $WS; catkin clean -y; popd +bash 1_prebuild.bash > 1_prebuild.out +rm -rf $WS +$SLOWRECORD --check --tall --buffer 0_quickstart.bash +bash 2_postbuild.bash > 2_postbuild.out + +popd diff --git a/docs/examples/ros_tutorials_ws/all.bash b/docs/examples/ros_tutorials_ws/all.bash new file mode 100755 index 00000000..6cd0f247 --- /dev/null +++ b/docs/examples/ros_tutorials_ws/all.bash @@ -0,0 +1,23 @@ +#!/usr/bin/env bash + +SLOWRECORD=$(pwd)/slowrecord +WS=/tmp/failure_ws + +pushd `dirname $0` + +rm -rf $WS + +source /opt/ros/indigo/setup.bash + +$SLOWRECORD --check --tall 0_checkout.bash +$SLOWRECORD --check --tall --buffer 1_init.bash +$SLOWRECORD --check --tall --buffer 2_dry_run.bash +$SLOWRECORD --check --tall 3_build.bash +$SLOWRECORD --check --tall 4_build_v.bash +$SLOWRECORD --check --tall 5_build_i.bash +$SLOWRECORD --check --tall 6_build_partial.bash +$SLOWRECORD --check --tall 7_build_this.bash +$SLOWRECORD --check --tall 8_build_start_with.bash +$SLOWRECORD --check --tall 9_build_no_deps.bash + +popd diff --git a/docs/history.rst b/docs/history.rst index 68ad0d82..0b1b6fca 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -83,6 +83,7 @@ Other functional improvements over ``catkin_make`` and ``catkin_make_isolated`` - Robustly adapting a build when packages are added to or removed from the **source space** - Context-aware building of a given package based on the working directory +- The ability to completely clean a single package's products from a workspace - Utilization of persistent build metadata which catches common errors - Support for different build "profiles" in a single workspace - Explicit control of workspace chaining diff --git a/docs/index.rst b/docs/index.rst index e97368c8..b341163a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,6 +44,7 @@ Catkin Command Line Tools :hidden: :maxdepth: 2 + Linked Devel Space Execution Engine .. toctree:: @@ -62,7 +63,7 @@ For documentation on creating catkin packages, see: http://docs.ros.org/api/catk .. note:: - This package was announced in March 2015 and is still in beta. A second beta release is planned for `February 2016 `. + This package was announced in March 2015 and is still in beta. A second beta release is planned for `April 2016 `. .. note:: diff --git a/docs/mechanics.rst b/docs/mechanics.rst index 78ddcbef..a17f8efb 100644 --- a/docs/mechanics.rst +++ b/docs/mechanics.rst @@ -21,15 +21,16 @@ display the standard configuration summary, as shown below: Profile: default Extending: None Workspace: /tmp/path/to/my_catkin_ws + -------------------------------------------------------------- Source Space: [exists] /tmp/path/to/my_catkin_ws/src + Log Space: [missing] /tmp/path/to/my_catkin_ws/logs Build Space: [missing] /tmp/path/to/my_catkin_ws/build Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel - Install Space: [missing] /tmp/path/to/my_catkin_ws/install - DESTDIR: None + Install Space: [unused] /tmp/path/to/my_catkin_ws/install + DESTDIR: [unused] None -------------------------------------------------------------- - Devel Space Layout: merged - Install Packages: False - Isolate Installs: False + Devel Space Layout: linked + Install Space Layout: merged -------------------------------------------------------------- Additional CMake Args: None Additional Make Args: None @@ -70,9 +71,10 @@ Build Product Layout Section - **Devel Space Layout** -- The organization of the **devel space**. + - *Linked* -- Write products from each package into independent isolated FHS trees, and symbolically link them into a merged FHS tree. + For more details, see `Linked Devel Space `_. - *Merged* -- Write products from all packages to a single FHS tree. This is most similar to the behavior of ``catkin_make``. - *Isolated* -- Write products from each package into independent isolated FHS trees. this is most similar to the behavior of ``catkin_make_isolated``. - - *Linked* -- Write products from each package into independent isolated FHS trees, and symbolically link them into a merged FHS tree. - **Install Packages** -- Enable creating and installation into the **install space**. - **Isolate Installs** -- Installs products into individual FHS subdirectories in the **install space**. @@ -107,18 +109,19 @@ Workspace Anatomy A standard catkin workspace, as defined by `REP-0128 `_, is a directory with a prescribed set of "spaces", each of which is contained within a directory under the workspace root. The spaces that comprise the workspace are described in the following sections. +In addition to the directories specified by `REP-0128 `_, ``catkin_tools`` also adds a visible ``logs`` directory and a hidden ``.catkin_tools`` directory. +The ``.catkin_tools`` directory stores persistent build configuration and profiles. =============== =============== ====================================================== Space Default Path Contents =============== =============== ====================================================== Source Space ``./src`` All source packages. + Log Space ``./logs`` Logs from building and cleaning. Build Space ``./build`` Intermediate build products for each package. Devel Space ``./devel`` FHS tree containing all final build products. Install Space ``./install`` FHS tree containing products of ``install`` targets. =============== =============== ====================================================== -In addition to these user-facing directories, ``catkin_tools`` also creates a hidden ``.catkin_tools`` directory, which stores persistent build configuration. - source space ------------ @@ -126,6 +129,25 @@ The **source space** contains all of the source packages to be built in the work The **source space** is also the only directory in the catkin workspace which is not modified by any ``catkin`` command verb. No build products are written to the source space, they are all built "out-of-source" in the **build space**, described in the next section. +log space +--------- + +The ``catkin`` command generates a log space, called ``logs`` by default, which contains build logs for each package. +Logs for each package are written in subdirectories with the same name as the package. + +The latest log for each verb and stage in a given package's log directory is also written with the format: + +.. code-block:: bash + + {VERB}.{STAGE}.log + +Each previous logfile has the following format, where ``{INDEX}`` begins at ``000`` and increases with each execution of that verb and stage: + +.. code-block:: bash + + {VERB}.{STAGE}.{INDEX}.log + + build space ----------- @@ -162,25 +184,6 @@ This directory both acts as a marker for the root of the workspace and contains This directory contains subdirectories representing different configuration profiles, and inside of each profile directory are YAML files which contain verb-specific metadata. It additionally contains a file which lists the name of the active configuration profile if it is different from ``default``. -Build Log Directory -~~~~~~~~~~~~~~~~~~~ - -The ``catkin`` command also generates a log directory called ``_logs`` in the **build space** and contains individual build logs for each package. -Logs for each package are written in subdirectories with the same name as the package. - -The latest log for each verb and stage in a given package's log directory is also written with the format: - -.. code-block:: bash - - {VERB}.{STAGE}.log - -Each previous logfile has the following format, where ``{INDEX}`` begins at ``000`` and increases with each execution of that verb and stage: - -.. code-block:: bash - - {VERB}.{STAGE}.{INDEX}.log - - Environment Setup Files ~~~~~~~~~~~~~~~~~~~~~~~ @@ -344,4 +347,3 @@ It will override the value of ``CMAKE_PREFIX_PATH`` and persist between builds. .. code-block:: bash Extending: [explicit] /tmp/path/to/other_ws - diff --git a/docs/quick_start.rst b/docs/quick_start.rst index 7ddcfa47..6d894081 100644 --- a/docs/quick_start.rst +++ b/docs/quick_start.rst @@ -15,7 +15,7 @@ The following is an example workflow and sequence of commands using default sett .. raw:: html -
+
Initializing a New Workspace ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -43,7 +43,7 @@ The value can come from a few different sources, and can be classified in one of - Implicit chaining via ``CMAKE_PREFIX_PATH`` environment or cache variable - Explicit chaining via ``catkin config --extend`` -For more information on the configuration summary and workspace chaining, see :doc:`Configuration Summary `. +For more information on the configuration summary and workspace chaining, see :doc:`Workspace Configuration `. For information on manipulating these options, see :doc:`the config verb `. .. note:: @@ -72,7 +72,7 @@ After these operations, your workspace's local directory structure would look li .. literalinclude:: examples/quickstart_ws/1_prebuild.bash :language: bash -.. literalinclude:: examples/quickstart_ws/1_prebuild.bash.out +.. literalinclude:: examples/quickstart_ws/1_prebuild.out :language: text Now that there are some packages in the workspace, Catkin has something to build. @@ -99,7 +99,7 @@ Calling ``catkin build`` will generate ``build`` and ``devel`` directories (as d .. literalinclude:: examples/quickstart_ws/2_postbuild.bash :language: bash -.. literalinclude:: examples/quickstart_ws/2_postbuild.bash.out +.. literalinclude:: examples/quickstart_ws/2_postbuild.out :language: text Intermediate build products (CMake cache files, Makefiles, object files, etc.) are generated in the ``build`` directory, or **build space** and final build products (libraries, executables, config files) are generated in the ``devel`` directory, or **devel space**. diff --git a/docs/verbs/catkin_build.rst b/docs/verbs/catkin_build.rst index 67a7deb2..8bc5a1c5 100644 --- a/docs/verbs/catkin_build.rst +++ b/docs/verbs/catkin_build.rst @@ -30,7 +30,7 @@ In addition to the listing the package names and in which order they would be bu .. raw:: html -
+
Building a Workspace -------------------- @@ -43,7 +43,7 @@ It automatically creates directories for a **build space** and a **devel space** .. raw:: html -
+
After the build finishes, the **build space** contains directories containing the intermediate build products for each package, and the **devel space** contains an FHS layout into which all the final build products are written. @@ -120,21 +120,21 @@ Additionally, if a package fails, the output to ``stderr`` is printed under the .. raw:: html -
+
All of the messages from the underlying jobs can be shown when using the ``-v`` or ``--verbose`` option. This will print the normal messages when a build job starts and finishes as well as the interleaved output to ``stdout`` and ``stderr`` from each build command in a block. .. raw:: html -
+
All output can be printed interleaved with the ``--interleave`` option. In this case, each line is prefixed with the job and stage from which it came. .. raw:: html -
+
Build Summary ------------- @@ -179,7 +179,7 @@ Specific packages can also be built by specifying them as positional arguments a .. raw:: html -
+
As shown above, only 4 packages (``roslib`` and its dependencies), of the total 36 packages would be built. @@ -194,7 +194,7 @@ This is equivalent to specifying the name of the package on the command line, an .. raw:: html -
+
Skipping Packages ----------------- @@ -211,7 +211,7 @@ You could use the ``--start-with`` option to continue the build where you left o .. raw:: html -
+
.. note:: @@ -230,7 +230,7 @@ This will skip all of the package's dependencies, build the given package, and t .. raw:: html -
+
Building and Running Tests ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/verbs/catkin_clean.rst b/docs/verbs/catkin_clean.rst index cc9f5fb5..d195a0fb 100644 --- a/docs/verbs/catkin_clean.rst +++ b/docs/verbs/catkin_clean.rst @@ -5,7 +5,101 @@ The ``clean`` verb makes it easier and safer to clean various products of a catk In addition to removing entire **build**, **devel**, and **install spaces**, it also gives you more fine-grained control over removing just parts of these directories. The ``clean`` verb is context-aware, but in order to work, it must be given the path to an initialized catkin workspace, or called from a path contained in an initialized catkin workspace. -This is because the paths to the relevant spaces are contained in a workspace's metadata directory. + +Space Cleaning +^^^^^^^^^^^^^^ + +For any configuration, any of the active profile's spaces can be cleaned entirely. +This includes any of the top-level directories which are configured for a given profile. +See the full command line interface for specifing specific spaces to clean. + +To clean all of the spaces for a given profile, you can call the ``clean`` verb without arguments: + +.. code-block:: bash + + catkin clean + +When running this command, ``catkin`` will prompt you to confirm that you want to delete the entire directories: + +.. code-block:: bash + + $ catkin clean + [clean] Warning: This will completely remove the following directories. (Use `--yes` to skip this check) + [clean] Log Space: /tmp/quickstart_ws/logs + [clean] Build Space: /tmp/quickstart_ws/build + [clean] Devel Space: /tmp/quickstart_ws/devel + + [clean] Are you sure you want to completely remove the directories listed above? [yN]: + +If you want to skip this check, you can use the ``--yes`` or ``-y`` options: + +.. code-block:: bash + + $ catkin clean -y + [clean] Removing develspace: /tmp/quickstart_ws/devel + [clean] Removing buildspace: /tmp/quickstart_ws/build + [clean] Removing log space: /tmp/quickstart_ws/logs + +.. note:: + + The ``clean`` verb will also ask for additional confirmation if any of the directories to be removed are outside of your workspace root. + To skip this additinal check, you can use the ``--force`` option. + +Partial Cleaning +^^^^^^^^^^^^^^^^ + +If a workspace is built with a ``linked`` **devel space**, the ``clean`` verb can be used to clean the products from individual packages. +This is possible since the ``catkin`` program will symbolically link the build products into the **devel space**, and stores a list of these links. + +Cleaning a Single Package +------------------------- + +Cleaning a single package (or serverla packages) is as simple as naming them: + +.. code-block:: bash + + catkin clean PKGNAME + +This will remove products from this package from the devel space, and remove its build space. + +Cleaning Products from Missing Packages +--------------------------------------- + +Sometimes, you may disable or remove source packages from your workspace's **source space**. +After packages have been removed from your **source space**, you can automatically clean the "orphaned" products with the following command: + +.. code-block:: bash + + catkin clean --orphans + +Cleaning Dependent Packages +--------------------------- + +When cleaning one package, it's sometimes useful to also clean all of the packages which depend on it. +This can prevent leftover elements from affecting the dependants. +To clean a package and only the packages which depend on it, you can run the following: + +.. code-block:: bash + + catkin clean --dependants PKGNAME + + +Cleaning Products from All Profiles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, the ``clean`` operating is applied only to the active or specified profile. +To apply it to *all* profiles, use the ``--all-profiles`` option. + +Cleaning Everything +^^^^^^^^^^^^^^^^^^^ + +If you want to clean **everything** except the source space (i.e. all files and folders generated by the ``catkin`` command, you can use ``--deinit`` to "deinitialize" the workspace. +This will clean all products from all packages for all profiles, as well as the profile metadata, itself. +After running this, a ``catkin_tools`` workspace will need to be reinitialized to be used. + +.. code-block:: bash + + catkin clean --deinit Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/verbs/cli/catkin_locate.txt b/docs/verbs/cli/catkin_locate.txt index a03acab9..a2a81cdf 100644 --- a/docs/verbs/cli/catkin_locate.txt +++ b/docs/verbs/cli/catkin_locate.txt @@ -1,5 +1,6 @@ usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e] - [-r] [-q] [-s | -b | -d | -i] + [-r] [-q] [-s | -b | -d | -i] [--shell-verbs] + [--examples] [PACKAGE] Get the paths to various locations in a workspace. @@ -37,3 +38,9 @@ Package Directories: -s foo` might return `/path/to/ws/src/foo`. PACKAGE The name of a package to locate. + +Special Directories: + Get the absolute path to a special catkin location + + --shell-verbs Get the path to the shell verbs script. + --examples Get the path to the examples directory. From 0c66a2f50dead82800ce193fdda0be9a7669b8dc Mon Sep 17 00:00:00 2001 From: Jonathan Bohren Date: Wed, 13 Apr 2016 19:13:55 -0400 Subject: [PATCH 08/10] docs: adding note on cmake isystem bug --- docs/troubleshooting.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 4d499038..70820ee6 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -33,6 +33,26 @@ Packages Are Being Built Out of Order - Run ``catkin list --deps /path/to/ws/src`` to list the dependencies of each package and look for errors. +Incorrect Resolution of Workspace Overlays +------------------------------------------ + +It's possible for a CMake package to include header directories as ``SYSTEM`` includes pointing to the workspace root include directory (like ``/path/to/ws/devel/include``). +If this happens, CMake will ignore any "normal" includes to that path, and prefer the ``SYSTEM`` include. +This means that ``/path/to/ws/devel/include`` will be searched *after* any other normal includes. +If another package specifies ``/opt/ros/indigo/include`` as a normal include, it will take precedence. + +- Minimal example here: https://github.com/jbohren/isystem +- Overview of GCC's system include precedence here: https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html + +As a workaround, you can force CMake to ignore all specified root include directories, and rely on CPATH for header resolution in these paths: + +.. code-block:: bash + + catkin config -a --cmake-args -DCMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES="/opt/ros/indigo/include" + +This is actually a bug in CMake and has been reported here: https://cmake.org/Bug/view.php?id=15970 + + Migration Problems ^^^^^^^^^^^^^^^^^^ From 8547bbfd7031434001fe35eb7aab5dc4d73af1c4 Mon Sep 17 00:00:00 2001 From: Jonathan Bohren Date: Wed, 13 Apr 2016 20:17:13 -0400 Subject: [PATCH 09/10] docs: Fixing a bunch of spelling errors, adding CI check --- .travis.before_install.bash | 2 +- .travis.yml | 3 ++- docs/advanced/catkin_shell_verbs.rst | 4 ++-- docs/advanced/job_executor.rst | 32 ++++++++++++------------- docs/advanced/verb_customization.rst | 2 +- docs/conf.py | 1 + docs/development/adding_build_types.rst | 2 +- docs/history.rst | 2 +- docs/migration.rst | 6 ++--- docs/spelling_wordlist.txt | 23 ++++++++++++++++++ docs/troubleshooting.rst | 6 ++--- docs/verbs/catkin_build.rst | 16 ++++++------- docs/verbs/catkin_clean.rst | 6 ++--- docs/verbs/catkin_config.rst | 8 +++---- docs/verbs/catkin_list.rst | 2 +- docs/verbs/catkin_profile.rst | 4 ++-- 16 files changed, 72 insertions(+), 47 deletions(-) create mode 100644 docs/spelling_wordlist.txt diff --git a/.travis.before_install.bash b/.travis.before_install.bash index 90216610..1015eaba 100755 --- a/.travis.before_install.bash +++ b/.travis.before_install.bash @@ -1,7 +1,7 @@ #!/usr/bin/env bash if [ "$TRAVIS_OS_NAME" == "linux" ]; then - echo "No Linux-specific before_install steps." + sudo apt-get install enchant elif [ "$TRAVIS_OS_NAME" == "osx" ]; then if [ "$PYTHON" == "/usr/local/bin/python3" ]; then brew install python3 diff --git a/.travis.yml b/.travis.yml index ded893d3..92ea69f8 100644 --- a/.travis.yml +++ b/.travis.yml @@ -35,7 +35,7 @@ matrix: before_install: # Install catkin_tools dependencies - source .travis.before_install.bash - - pip install setuptools argparse catkin-pkg distribute PyYAML psutil trollius osrf_pycommon + - pip install setuptools argparse catkin-pkg distribute PyYAML psutil trollius osrf_pycommon pyenchant sphinxcontrib-spelling install: # Install catkin_tools - python setup.py develop @@ -55,6 +55,7 @@ script: # Build documentation - pushd docs - make html + - sphinx-build -b spelling . build - popd notifications: email: false diff --git a/docs/advanced/catkin_shell_verbs.rst b/docs/advanced/catkin_shell_verbs.rst index 29b341a4..72031efa 100644 --- a/docs/advanced/catkin_shell_verbs.rst +++ b/docs/advanced/catkin_shell_verbs.rst @@ -11,7 +11,7 @@ When you source the resulting file, you can use ``bash``/``zsh`` shell functions Provided verbs are: - ``catkin cd`` -- Change to package directory in source space. -- ``catkin source`` -- Source the develspace or installspace of the containing workspace. +- ``catkin source`` -- Source the devel space or install space of the containing workspace. Full Command-Line Interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -24,7 +24,7 @@ Change to package directory in source space with `cd` verb. ARGS are any valid catkin locate arguments -The `source` verb sources the develspace or installspace of the containing workspace. +The `source` verb sources the devel space or install space of the containing workspace. .. code-block:: text diff --git a/docs/advanced/job_executor.rst b/docs/advanced/job_executor.rst index 657cf7f3..2df3cd11 100644 --- a/docs/advanced/job_executor.rst +++ b/docs/advanced/job_executor.rst @@ -2,7 +2,7 @@ The Catkin Execution Engine =========================== One of the core modules in ``catkin_tools`` is the **job executor**. -The executor performs jobs required to complete a task in a way that maximizes (or achives a specific) resource utilization subject to job dependency constraints. +The executor performs jobs required to complete a task in a way that maximizes (or achieves a specific) resource utilization subject to job dependency constraints. The executor is closely integrated with logging and job output capture. This page details the design and implementation of the executor. @@ -13,7 +13,7 @@ The execution model is fairly simple. The executor executes a single **task** for a given command (i.e. ``build``, ``clean``, etc.). A **task** is a set of **jobs** which are related by an acyclic dependency graph. -Each **job** is given a unique identifier and is composed of a set of dependencies and a sequence of executable **stages**, which are arbitrary functions or subprocess calls which utilize one or more **workers** to be executed. +Each **job** is given a unique identifier and is composed of a set of dependencies and a sequence of executable **stages**, which are arbitrary functions or sub-process calls which utilize one or more **workers** to be executed. The allocation of workers is managed by the **job server**. Throughout execution, synchronization with the user-facing interface and output formatting are mediated by a simple **event queue**. @@ -21,22 +21,22 @@ The executor is single-threaded and uses an asynchronous loop to execute jobs as If a job contains blocking stages it can utilize a normal thread pool for execution, but is still only guaranteed one worker by the main loop of the executor. See the following section for more information on workers and the job server. -The input to the executor is a list of topologically-sorted jobs with no circular dependencies and some parameters which control the jobserver behavior. +The input to the executor is a list of topologically-sorted jobs with no circular dependencies and some parameters which control the job server behavior. These behavior parameters are explained in detail in the following section. -Each job is in one of the following lifecycle states at any time: +Each job is in one of the following life-cycle states at any time: - ``PENDING`` Not ready to be executed (dependencies not yet completed) - ``QUEUED`` Ready to be executed once workers are available - ``ACTIVE`` Being executed by one or more workers - - ``FINISHED`` Has been executed and either succeded or failed (terminal) + - ``FINISHED`` Has been executed and either succeeded or failed (terminal) - ``ABANDONED`` Was not built because a prerequisite was not met (terminal) .. figure:: executor_job_lifecycle.svg :scale: 50 % - :alt: Executor Job Lifecycle + :alt: Executor Job Life-cycle - **Executor Job lifecycle** + **Executor Job Life-cycle** All jobs begin in the ``PENDING`` state, and any jobs with unsatisfiable dependencies are immediately set to ``ABANDONED``, and any jobs without dependencies are immediately set to ``QUEUED``. After the state initialization, the executor processes jobs in a main loop until they are in one of the two terminal states (``FINISHED`` or ``ABANDONED``). @@ -46,7 +46,7 @@ Each main loop iteration does the following: - Report status of all jobs to the event queue - Retrieve ``ACTIVE`` job futures which have completed and set them ``FINISHED`` - Check for any ``PENDING`` jobs which need to be ``ABANDONED`` due to failed jobs - - Change all ``PENDING`` jobs whose dependencies are satisifed to ``QUEUED`` + - Change all ``PENDING`` jobs whose dependencies are satisfied to ``QUEUED`` Once each job is in one of terminal states, the executor pushes a final status event and returns. @@ -59,7 +59,7 @@ Once a job is started, it is assigned a single worker from the job server. These are considered **top-level jobs** since they are managed directly by the catkin executor. The number of top-level jobs can be configured for a given task. -Additionally to top-level paralellism, some job stages are capable of running in parallel, themselves. +Additionally to top-level parallelism, some job stages are capable of running in parallel, themselves. In such cases, the job server can interface directly with the underlying stage's low-level job allocation. This enables multi-level parallelism without allocating more than a fixed number of jobs. @@ -67,7 +67,7 @@ This enables multi-level parallelism without allocating more than a fixed number :scale: 50 % :alt: Executor job resources - **Executor Job Flow and Resource Utilization** -- In this snapshot of the job pipeline, the executor is executing four of six possible top-level jobs, each with three stages, and using sevel of eight total workers. Two jobs are executing subprocesses, which have side-channel communication with the job server. + **Executor Job Flow and Resource Utilization** -- In this snapshot of the job pipeline, the executor is executing four of six possible top-level jobs, each with three stages, and using seven of eight total workers. Two jobs are executing sub-processes, which have side-channel communication with the job server. One such parallel-capable stage is the GNU Make build stage. In this case, the job server implements a GNU Make job server interface, which involves reading and writing tokens from file handles passed as build flags to the Make command. @@ -91,21 +91,21 @@ Jobs and Job Stages ^^^^^^^^^^^^^^^^^^^ As mentioned above, a **job** is a set of dependencies and a sequence of **job stages**. -Jobs and stages are constructed before a given task starts executing, and hold only specificaitons of what needs to be done to complete them. +Jobs and stages are constructed before a given task starts executing, and hold only specifications of what needs to be done to complete them. All stages are given a label for user introspection, a logger interface, and can either require or not require allocation of a worker from the job server. Stage execution is performed asynchronously by Python's ``asyncio`` module. This means that exceptions thrown in job stages are handled directly by the executor. It also means job stages can be interrupted easily through Python's normal signal handling mechanism. -Stages can either be **command stages** (subprocess commands) or **function stages** (python functions). +Stages can either be **command stages** (sub-process commands) or **function stages** (python functions). In either case, loggers used by stages support segmentation of ``stdout`` and ``stderr`` from job stages for both real-time introspection and logging. Command Stages ~~~~~~~~~~~~~~~ -In addition to the basic arguments mentioned above, command stages are paramterized by the standard subprocess command arguments including the following: +In addition to the basic arguments mentioned above, command stages are paramterized by the standard sub-process command arguments including the following: - The command, itself, and its arguments, - The working directory for the command, @@ -114,7 +114,7 @@ In addition to the basic arguments mentioned above, command stages are paramteri - Whether to emulate a TTY - Whether to partition ``stdout`` and ``stderr`` -When executed, command stages use ``asncio``'s asynchronous process executor with a custom I/O protocol. +When executed, command stages use ``asyncio``'s asynchronous process executor with a custom I/O protocol. Function Stages ~~~~~~~~~~~~~~~ @@ -122,7 +122,7 @@ Function Stages In addition to the basic arguments mentioned above, function stages are parameterized by a function handle and a set of function-specific Python arguments and keyword arguments. When executed, they use the thread pool mentioned above. -Since the function stages aren't subprocesses, I/O isn't piped or redirected. +Since the function stages aren't sub-processes, I/O isn't piped or redirected. Instead, a custom I/O logger is passed to the function for output. Functions used as function stages should use this logger to write to ``stdout`` and ``stderr`` instead of using normal system calls. @@ -153,5 +153,5 @@ The modeled events include the following: - ``STAGE_PROGRESS`` A job stage has executed partially, - ``STDOUT`` A status message from a job, - ``STDERR`` A warning or error message from a job, - - ``SUBPROCESS`` A subprocess has been created, + - ``SUBPROCESS`` A sub process has been created, - ``MESSAGE`` Arbitrary string message diff --git a/docs/advanced/verb_customization.rst b/docs/advanced/verb_customization.rst index 8e84779a..048d34ea 100644 --- a/docs/advanced/verb_customization.rst +++ b/docs/advanced/verb_customization.rst @@ -22,7 +22,7 @@ Below are the built-in aliases as displayed by this command: Defining Additional Aliases ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Verb aliases are defined in the ``verb_aliases`` subdirectory of the catkin config folder, ``~/.config/catkin/verb_aliases``. +Verb aliases are defined in the ``verb_aliases`` sub-directory of the catkin config folder, ``~/.config/catkin/verb_aliases``. Any YAML files in that folder (files with a ``.yaml`` extension) will be processed as definition files. These files are formatted as simple YAML dictionaries which map aliases to expanded expressions, which must be composed of other ``catkin`` verbs, options, or aliases: diff --git a/docs/conf.py b/docs/conf.py index 20a4795f..f45929df 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,6 +34,7 @@ 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.viewcode', + 'sphinxcontrib.spelling', #'sphinxcontrib.programoutput', #'sphinxcontrib.ansi', ] diff --git a/docs/development/adding_build_types.rst b/docs/development/adding_build_types.rst index bbfd408f..01ccb18b 100644 --- a/docs/development/adding_build_types.rst +++ b/docs/development/adding_build_types.rst @@ -9,7 +9,7 @@ The current release of ``catkin_tools`` supports building two types of packages: In order to fully support additional build types, numerous additions need to be made to the command-line interfaces so that the necessary parameters can be passed to the ``build`` verb. For partial support, however, all that's needded is to add a build type identifier and a function for generating build jobs. -The supported build typs are easily extendable using the ``setuptools`` ``entry_points`` interface without modifying the ``catkin_tools`` project, itself. +The supported build types are easily extendable using the ``setuptools`` ``entry_points`` interface without modifying the ``catkin_tools`` project, itself. Regardless of what package the ``entry_point`` is defined in, it will be defined in the ``setup.py`` of that package, and will take this form: .. code-block:: python diff --git a/docs/history.rst b/docs/history.rst index 0b1b6fca..a17f998f 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -32,7 +32,7 @@ These defaults would result in the execution of the following commands: $ cmake ../src -DCATKIN_DEVEL_SPACE=../devel -DCMAKE_INSTALL_PREFIX=../install $ make -j -l [optional target, e.g. install] -An advantage of this approach is that the total configuration would be smaller than configuring each package individually and that the Make targets can be parallelized even amongst dependent packages. +An advantage of this approach is that the total configuration would be smaller than configuring each package individually and that the Make targets can be parallelized even among dependent packages. In practice, however, it also means that in large workspaces, modification of the CMakeLists.txt of one package would necessitate the reconfiguration of all packages in the entire workspace. diff --git a/docs/migration.rst b/docs/migration.rst index 3f655e38..3d30f9ae 100644 --- a/docs/migration.rst +++ b/docs/migration.rst @@ -38,10 +38,10 @@ Since all packages are built in isolation with ``catkin build``, you can't rely Migration Troubleshooting ^^^^^^^^^^^^^^^^^^^^^^^^^ -When migrating from ``catkin_make`` to catkin build, the most common problems come from Catkin packages taking advantge of package cross-talk in the CMake configuration stage. +When migrating from ``catkin_make`` to catkin build, the most common problems come from Catkin packages taking advantage of package cross-talk in the CMake configuration stage. Many Catkin packages implicitly rely on other packages in a workspace to declare and find dependencies. -When switcing from ``catkin_make``, users will often discover these bugs. +When switching from ``catkin_make``, users will often discover these bugs. Common Issues ------------- @@ -200,7 +200,7 @@ CLI Comparison with ``catkin_make`` and ``catkin_make_isolated`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Below are tables mapping ``catkin_make`` and ``catkin_make_isolated`` arguments into ``catkin`` arguments. -Note that some ``catkin_make`` options can only be achived with the ``catkin config`` verb. +Note that some ``catkin_make`` options can only be achieved with the ``catkin config`` verb. ================================================= ============================================ catkin_make ... catkin ... diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt new file mode 100644 index 00000000..3769b3ce --- /dev/null +++ b/docs/spelling_wordlist.txt @@ -0,0 +1,23 @@ +CMake +whitelist +whitelisted +Whitelisting +Quickstart +workflow +devel +env +metadata +buildtools +config +devel +deinitialize +dependants +args +extendable +preprocess +autotools +prebuild +internet +buildtool +logfile +unsetting diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 70820ee6..1c154a25 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -11,14 +11,14 @@ The ``catkin`` tool will detect the following issues automatically. Missing Workspace Components ---------------------------- -- Uninitialized workspace (mising ``.catkin_tools`` directory) +- Uninitialized workspace (missing ``.catkin_tools`` directory) - Missing **source space** as specified by the configuration Inconsistent Environment ------------------------ -- The ``CMAKE_PREFIX_PATH`` environment variable is different than the cahced ``CMAKE_PREFIX_PATH`` -- The explicitly extended workspace path yeilds a different ``CMAKE_PREFIX_PATH`` than the cached ``CMAKE_PREFIX_PATH`` +- The ``CMAKE_PREFIX_PATH`` environment variable is different than the cached ``CMAKE_PREFIX_PATH`` +- The explicitly extended workspace path yields a different ``CMAKE_PREFIX_PATH`` than the cached ``CMAKE_PREFIX_PATH`` - The **build space** or **devel space** was built with a different tool such as ``catkin_make`` or ``catkin_make_isolated`` - The **build space** or **devel space** was built in a different isolation mode diff --git a/docs/verbs/catkin_build.rst b/docs/verbs/catkin_build.rst index 8bc5a1c5..8055cf14 100644 --- a/docs/verbs/catkin_build.rst +++ b/docs/verbs/catkin_build.rst @@ -77,7 +77,7 @@ This is sometimes required when running ``catkin build`` from within a program t Console Messages ---------------- -Normally, unless an error occurs, the output from each package's build proces is collected but not printed to the console. +Normally, unless an error occurs, the output from each package's build process is collected but not printed to the console. All that is printed is a pair of messages designating the start and end of a package's build. This is formatted like the following for the ``genmsg`` package: @@ -140,7 +140,7 @@ Build Summary ------------- At the end of each build, a brief build summary is printed to guarantee that anomalies aren't missed. -This summary displays the total runtime, the number of successful jobs, the number of jobs which produced warnings, and the number of jobs which weren't attempted due to failed dependencies. +This summary displays the total run-time, the number of successful jobs, the number of jobs which produced warnings, and the number of jobs which weren't attempted due to failed dependencies. .. code-block:: none @@ -201,7 +201,7 @@ Skipping Packages Suppose you built every package up to ``roslib``, but that package had a build error. After fixing the error, you could run the same build command again, but the ``build`` verb provides an option to save time in this situation. -If re-started from the beginning, none of the products of the dependencies of ``roslib`` would be re-built, but it would still take some time for the underlying byuildsystem to verify that for each package. +If re-started from the beginning, none of the products of the dependencies of ``roslib`` would be re-built, but it would still take some time for the underlying build system to verify that for each package. Those checks could be skipped, however, by jumping directly to a given package. You could use the ``--start-with`` option to continue the build where you left off after fixing the problem. @@ -291,7 +291,7 @@ Advanced Options Temporarily Changing Build Flags -------------------------------- -While the build configuratoin flags are set and stored in the build context, it's possible to temporarily override or augment them when using the ``build`` verb. +While the build configuration flags are set and stored in the build context, it's possible to temporarily override or augment them when using the ``build`` verb. .. code-block:: bash @@ -313,13 +313,13 @@ This command passes the ``-DCMAKE_C_FLAGS=...`` arugment to all invocations of ` Configuring Build Jobs ---------------------- -By default ``catkin build`` on a computer with ``N`` cores will build up to ``N`` packages in parallel and will distribute ``N`` ``make`` jobs among them using an internal jobserver. -If your platform doesn't support jobserver scheduling, ``catkin build`` will pass ``-jN -lN`` to ``make`` for each package. +By default ``catkin build`` on a computer with ``N`` cores will build up to ``N`` packages in parallel and will distribute ``N`` ``make`` jobs among them using an internal job server. +If your platform doesn't support job server scheduling, ``catkin build`` will pass ``-jN -lN`` to ``make`` for each package. You can control the maximum number of packages allowed to build in parallel by using the ``-p`` or ``--parallel-packages`` option and you can change the number of ``make`` jobs available with the ``-j`` or ``--jobs`` option. By default, these jobs options aren't passed to the underlying ``make`` command. -To disable the jobserver, you can use the ``--no-jobserver`` option, and you can pass flags directly to ``make`` with the ``--make-args`` option. +To disable the job server, you can use the ``--no-jobserver`` option, and you can pass flags directly to ``make`` with the ``--make-args`` option. .. note:: @@ -342,7 +342,7 @@ For example, to specify that ``catkin build`` should not start additional parall $ catkin build --mem-limit 50% -Alternatively, if it sohuld not start additional jobs when over 4GB of memory is used, you can specifiy: +Alternatively, if it should not start additional jobs when over 4GB of memory is used, you can specify: .. code-block:: bash diff --git a/docs/verbs/catkin_clean.rst b/docs/verbs/catkin_clean.rst index d195a0fb..385f6b59 100644 --- a/docs/verbs/catkin_clean.rst +++ b/docs/verbs/catkin_clean.rst @@ -11,7 +11,7 @@ Space Cleaning For any configuration, any of the active profile's spaces can be cleaned entirely. This includes any of the top-level directories which are configured for a given profile. -See the full command line interface for specifing specific spaces to clean. +See the full command line interface for specifying specific spaces to clean. To clean all of the spaces for a given profile, you can call the ``clean`` verb without arguments: @@ -43,7 +43,7 @@ If you want to skip this check, you can use the ``--yes`` or ``-y`` options: .. note:: The ``clean`` verb will also ask for additional confirmation if any of the directories to be removed are outside of your workspace root. - To skip this additinal check, you can use the ``--force`` option. + To skip this additional check, you can use the ``--force`` option. Partial Cleaning ^^^^^^^^^^^^^^^^ @@ -54,7 +54,7 @@ This is possible since the ``catkin`` program will symbolically link the build p Cleaning a Single Package ------------------------- -Cleaning a single package (or serverla packages) is as simple as naming them: +Cleaning a single package (or several packages) is as simple as naming them: .. code-block:: bash diff --git a/docs/verbs/catkin_config.rst b/docs/verbs/catkin_config.rst index b02631da..1b1da128 100644 --- a/docs/verbs/catkin_config.rst +++ b/docs/verbs/catkin_config.rst @@ -1,15 +1,15 @@ ``catkin config`` -- Configure a Workspace ========================================== -The ``config`` verb can be used to both view and mapiulate a workspace's configuration options. -These options include all of the elements listed in thr configuration summary. +The ``config`` verb can be used to both view and manipulate a workspace's configuration options. +These options include all of the elements listed in the configuration summary. By default, the ``config`` verb gets and sets options for a workspace's *active* profile. If no profiles have been specified for a workspace, this is a default profile named ``default``. .. note:: - Calling ``catkin config`` on an uninitialied workspace will not automatically initialize it unless it is used with the ``--init`` option. + Calling ``catkin config`` on an uninitialized workspace will not automatically initialize it unless it is used with the ``--init`` option. Viewing the Configuration Summary ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -167,7 +167,7 @@ This means that blacklisted packages will not be built even if another package i .. note:: Blacklisting a package does not remove it's build directory or build - products, it only pevents it from being rebuilt. + products, it only prevents it from being rebuilt. To set the blacklist, you can call the following command: diff --git a/docs/verbs/catkin_list.rst b/docs/verbs/catkin_list.rst index 0726157e..9daf8c8b 100644 --- a/docs/verbs/catkin_list.rst +++ b/docs/verbs/catkin_list.rst @@ -2,7 +2,7 @@ ==================================== The ``list`` verb for the ``catkin`` command is used to find and list information about catkin packages. -By default, it will list the packages in the workspace containing the current working directoy. +By default, it will list the packages in the workspace containing the current working directory. It can also be used to list the packages in any other arbitrary directory. Checking for Catkin Package Warnings diff --git a/docs/verbs/catkin_profile.rst b/docs/verbs/catkin_profile.rst index b7c863b5..2dedff54 100644 --- a/docs/verbs/catkin_profile.rst +++ b/docs/verbs/catkin_profile.rst @@ -4,7 +4,7 @@ Many verbs contain a ``--profile`` option, which selects which configuration profile to use, without which it will use the "active" profile. The ``profile`` verb enables you to manager the available profiles as well as set the "active" profile when using other verbs. -Even without using the ``profile`` verb, any use of the ``catkin`` command which changes the workspace is impliclty using a configuration profile called ``default``. +Even without using the ``profile`` verb, any use of the ``catkin`` command which changes the workspace is implicitly using a configuration profile called ``default``. The ``profile`` verb has several sub-commands for profile management. These include the following: @@ -60,7 +60,7 @@ To see these effects, you can run ``catkin config`` to write a default configura [profile] Available profiles: - default (active) -The ``profile`` verb now shows that the profile named "default" is avialable and is active. +The ``profile`` verb now shows that the profile named "default" is available and is active. Calling ``catkin config`` with the ``--profile`` argument will automatically create a profile based on the given configuration options: .. code-block:: bash From a2e21ee87e8874c7db5edfc5dac9ad6262dd37f8 Mon Sep 17 00:00:00 2001 From: Jonathan Bohren Date: Wed, 13 Apr 2016 22:35:23 -0400 Subject: [PATCH 10/10] docs: fixing typos, adding -y for CI build --- .travis.before_install.bash | 2 +- docs/advanced/job_executor.rst | 2 +- docs/cheat_sheet.rst | 10 ++++---- docs/development/adding_build_types.rst | 2 +- docs/installing.rst | 2 +- docs/mechanics.rst | 10 ++++---- docs/migration.rst | 4 ++-- docs/quick_start.rst | 2 +- docs/spelling_wordlist.txt | 32 +++++++++++++------------ docs/verbs/catkin_build.rst | 2 +- 10 files changed, 35 insertions(+), 33 deletions(-) diff --git a/.travis.before_install.bash b/.travis.before_install.bash index 1015eaba..6c97c062 100755 --- a/.travis.before_install.bash +++ b/.travis.before_install.bash @@ -1,7 +1,7 @@ #!/usr/bin/env bash if [ "$TRAVIS_OS_NAME" == "linux" ]; then - sudo apt-get install enchant + sudo apt-get install enchant -y elif [ "$TRAVIS_OS_NAME" == "osx" ]; then if [ "$PYTHON" == "/usr/local/bin/python3" ]; then brew install python3 diff --git a/docs/advanced/job_executor.rst b/docs/advanced/job_executor.rst index 2df3cd11..4c742bb3 100644 --- a/docs/advanced/job_executor.rst +++ b/docs/advanced/job_executor.rst @@ -105,7 +105,7 @@ In either case, loggers used by stages support segmentation of ``stdout`` and `` Command Stages ~~~~~~~~~~~~~~~ -In addition to the basic arguments mentioned above, command stages are paramterized by the standard sub-process command arguments including the following: +In addition to the basic arguments mentioned above, command stages are parameterized by the standard sub-process command arguments including the following: - The command, itself, and its arguments, - The working directory for the command, diff --git a/docs/cheat_sheet.rst b/docs/cheat_sheet.rst index 69dfe513..3f8dfdeb 100644 --- a/docs/cheat_sheet.rst +++ b/docs/cheat_sheet.rst @@ -17,7 +17,7 @@ Initialize a workspace with a default layout (``src``/``build``/``devel``) in th ... with a default layout in a *different* directory: - ``catkin init --workspace /tmp/path/to/my_catkin_ws`` -... which explicity extends another workspace: +... which explicitly extends another workspace: - ``catkin config --init --extend /opt/ros/hydro`` Initialize a workspace with a **source space** called ``other_src``: @@ -32,7 +32,7 @@ Configuring Workspaces View the current configuration: - ``catkin config`` -Setting and un-setting CMake options: +Setting and unsetting CMake options: - ``catkin config --cmake-args -DENABLE_CORBA=ON -DCORBA_IMPLEMENTATION=OMNIORB`` - ``catkin config --no-cmake-args`` @@ -63,7 +63,7 @@ Build the package containing the current working directory: ... but don't rebuild its dependencies: - ``catkin build --this --no-deps`` -Build packages with aditional CMake args: +Build packages with additional CMake args: - ``catkin build --cmake-args -DCMAKE_BUILD_TYPE=Debug`` ... and save them to be used for the next build: @@ -133,8 +133,8 @@ Change from explicit to implicit chaining: catkin clean -a catkin config --no-extend -Building With Other Jobservers -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Building With Other Job Servers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Build with ``distcc``: .. code-block:: bash diff --git a/docs/development/adding_build_types.rst b/docs/development/adding_build_types.rst index 01ccb18b..c5408537 100644 --- a/docs/development/adding_build_types.rst +++ b/docs/development/adding_build_types.rst @@ -7,7 +7,7 @@ The current release of ``catkin_tools`` supports building two types of packages: - **CMake** -- "Plain" CMake packages In order to fully support additional build types, numerous additions need to be made to the command-line interfaces so that the necessary parameters can be passed to the ``build`` verb. -For partial support, however, all that's needded is to add a build type identifier and a function for generating build jobs. +For partial support, however, all that's needed is to add a build type identifier and a function for generating build jobs. The supported build types are easily extendable using the ``setuptools`` ``entry_points`` interface without modifying the ``catkin_tools`` project, itself. Regardless of what package the ``entry_point`` is defined in, it will be defined in the ``setup.py`` of that package, and will take this form: diff --git a/docs/installing.rst b/docs/installing.rst index 409a2170..d076e9ff 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -6,7 +6,7 @@ You can install the ``catkin_tools`` package as a binary through a package manag .. note:: This project is still in beta and has not been released yet, please install from source. - In particular, interface and behaviour are still subject to incompatible changes. + In particular, interface and behavior are still subject to incompatible changes. If you rely on a stable environment, please use ``catkin_make`` instead of this tool. Installing on Ubuntu with apt-get diff --git a/docs/mechanics.rst b/docs/mechanics.rst index a17f8efb..100c158d 100644 --- a/docs/mechanics.rst +++ b/docs/mechanics.rst @@ -2,8 +2,8 @@ Workspace Mechanics =================== This chapter defines the organization, composition, and use of Catkin workspaces. -Catkin workspaces enable rapid simulatnous building and executing of numerous interdependent projects. -These projects do not need to share the sme buildtool, but they do need to be able to either build or install to a FHS tree. +Catkin workspaces enable rapid simultaneous building and executing of numerous interdependent projects. +These projects do not need to share the same build tool, but they do need to be able to either build or install to a FHS tree. Unlike integrated development environments (IDEs) which normally only manage single projects, the purpose of Catkin is to enable the simultaneous compilation of numerous independently-authored projects. @@ -161,8 +161,8 @@ devel space Build products like executables, libraries, pkg-config files, and CMake config files, are generated in the **devel space**. The **devel space** is organized as an `FHS `_ tree. -Some buildtools simply treat the **devel space** as an install prefix, but other buildtools like ``catkin``, itself, can build targets directly into the **devel space** in order to skip the additional install step. -For such packages, executing programs from the develspace sometimes requires that the source space is still available. +Some build tools simply treat the **devel space** as an install prefix, but other buildtools like ``catkin``, itself, can build targets directly into the **devel space** in order to skip the additional install step. +For such packages, executing programs from the **devel space** sometimes requires that the source space is still available. At the root of the **devel space** is a set of environment setup files which can be "sourced" in order to properly execute the space's products. @@ -187,7 +187,7 @@ It additionally contains a file which lists the name of the active configuration Environment Setup Files ~~~~~~~~~~~~~~~~~~~~~~~ -The FHS trees of the **devel space** and **install space** also contain several environemnt "setup" scripts. +The FHS trees of the **devel space** and **install space** also contain several environment "setup" scripts. These setup scripts are intended to make it easier to use the resulting FHS tree for building other source code or for running programs built by the packages in the workspace. The setup script can be used like this in ``bash``: diff --git a/docs/migration.rst b/docs/migration.rst index 3d30f9ae..ce6536c7 100644 --- a/docs/migration.rst +++ b/docs/migration.rst @@ -5,7 +5,7 @@ Important Distinctions between ``catkin_make`` and ``catkin build`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Unlike ``catkin_make``, the ``catkin`` command-line tool is not just a thin wrapper around a ``CMake`` use pattern. -The ``catkin build`` command builds each package in a workspace's source space *in isolation* in order to prevent buildtime cross-talk. +The ``catkin build`` command builds each package in a workspace's source space *in isolation* in order to prevent build-time cross-talk. As such, in its simplest use, ``catkin build`` is like a parallelized version of ``catkin_make_isolated``. While there are many more features in ``catkin_tools`` described in the rest of the documentation, this chapter provides details on how to switch from using ``catkin_make`` or ``catkin_make_isolated``. @@ -279,4 +279,4 @@ Note that some ``catkin_make`` options can only be achieved with the ``catkin co will continue to persist until changed. .. [2] These options, if passed to ``catkin build`` only affect that invocation. If passed to ``catkin config``, they will persist to - subseqent calls to ``catkin build``. + subsequent calls to ``catkin build``. diff --git a/docs/quick_start.rst b/docs/quick_start.rst index 6d894081..c3dea6e6 100644 --- a/docs/quick_start.rst +++ b/docs/quick_start.rst @@ -67,7 +67,7 @@ The shell interaction below shows the creation of four empty packages: ``pkg_a`` :language: bash :lines: 5-10 -After these operations, your workspace's local directory structure would look like the followng (to two levels deep): +After these operations, your workspace's local directory structure would look like the following (to two levels deep): .. literalinclude:: examples/quickstart_ws/1_prebuild.bash :language: bash diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 3769b3ce..e2a8a57f 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -1,23 +1,25 @@ -CMake -whitelist -whitelisted -Whitelisting -Quickstart -workflow -devel -env -metadata +args +autotools +buildsystem +buildtool buildtools +CMake config -devel deinitialize +dependant dependants -args +devel +devel +env extendable -preprocess -autotools -prebuild internet -buildtool logfile +metadata +prebuild +preprocess +Quickstart unsetting +whitelist +whitelisted +Whitelisting +workflow diff --git a/docs/verbs/catkin_build.rst b/docs/verbs/catkin_build.rst index 8055cf14..defd1e35 100644 --- a/docs/verbs/catkin_build.rst +++ b/docs/verbs/catkin_build.rst @@ -307,7 +307,7 @@ To achieve this, use a command similar to this: $ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter" -This command passes the ``-DCMAKE_C_FLAGS=...`` arugment to all invocations of ``cmake``. +This command passes the ``-DCMAKE_C_FLAGS=...`` argument to all invocations of ``cmake``. Configuring Build Jobs