{"action":"created","comment":{"url":"https://api.github.com/repos/catkin/catkin_tools/pulls/comments/59949693","id":59949693,"diff_hunk":"@@ -4,36 +4,93 @@ Migrating from catkin_make\n Important Distinctions between ``catkin_make`` and ``catkin build``\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n \n-Unlike ``catkin_make``, the ``catkin`` command-line tool is not just a thin wrapper around a ``CMake`` use pattern.\n+Unlike ``catkin_make``, the ``catkin`` command-line tool is not just a thin wrapper around a the ``cmake`` and ``make`` commands.\n The ``catkin build`` command builds each package in a workspace's source space *in isolation* in order to prevent build-time cross-talk.\n-As such, in its simplest use, ``catkin build`` is like a parallelized version of ``catkin_make_isolated``.\n-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``.\n+As such, in its simplest use, ``catkin build`` behaves similarly to a parallelized version of ``catkin_make_isolated``.\n \n-Operational Differences\n-^^^^^^^^^^^^^^^^^^^^^^^\n+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`` and ``catkin_make_isolated``.\n+This chapter does not describe advanced features that ``catkin_tools`` provides over ``catkin_make`` and ``catkin_make_isolated``. \n+For a quick overview of what you can do with ``catkin build``, see the :doc:`Cheat Sheet <cheat_sheet>`.\n \n-- ``catkin_tools`` has no \"top-level\" ``CMakeLists.txt`` file.\n-  The **source   space** simply contains a collection of packages.\n-  If you have been modifying   this ``CMakeLists.txt`` file, those modifications will be ignored.\n+Implications of Isolation\n+--------------------------\n+\n+Build isolation has the following implications for both ``catkin_make_isolated`` and ``catkin build``:\n+\n+- There is no \"top-level\" ``CMakeLists.txt`` file in the **source space**.\n - Each package in a ``catkin_tools`` workspace has its own isolated build space.\n-- ``catkin build`` can be run from any directory under the workspace root.\n-- ``catkin config`` stores many workspace configuration options which needed to be passed to each call of ``catkin_make``.\n-- ``catkin build`` can build plain CMake packages if they have ``package.xml`` files.\n - Packages built with ``catkin build`` can not access variables defined in other Catkin packages in the same workspace.\n-- Packages no longer need to define target dependencies on ROS messages built in other packages.\n-  All targets in a dependency are guaranteed to have been   built before the current package.\n-- ``catkin_tools`` and ``catkin_make`` can use the same source space, but they must use different build, devel, and install spaces.\n-- ``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.\n-- ``catkin build`` passes CMake command line arguments to multiple packages.\n-  Since not all packages accept the same CMake arguments, the ``cmake`` command is invoked with ``--no-warn-unused-cli``.\n-  This means there will be no warnings for unused variables passed to ``cmake``.\n+- All targets in each of a package's dependencies are guaranteed to have been built before the current package.\n+- Packages do not need to define target dependencies on ROS messages built in other packages.\n+- Plain CMake packages can be built if they each have a ``package.xml`` file with the appropriate `<build_type> tag <http://www.ros.org/reps/rep-0140.html#build-type>`_.\n \n-IDE Integration\n-^^^^^^^^^^^^^^^\n+Additional Differences with ``catkin build``\n+--------------------------------------------\n \n-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.\n+In addition to the differences due to isolation, ``catkin build`` is also different from ``catkin_make_isolated`` in the following ways:\n+\n+- It builds packages in parallel, using an internal job server to distribute load.\n+- It puts products into hidden directories, and then symbolically links them into the **devel space**.\n+- It stores persistent configuration options in a ``.catkin_tools`` directory at the root of your workspace.\n+- It passes the same CMake command line arguments to multiple packages.\n+- It passes ``--no-warn-unused-cli`` to the ``cmake`` command since not all packages accept the same CMake arguments.\n+- It generates ``.catkin`` files where each source package is listed, individually, instead of just listing the source space for the workspace.","path":"docs/migration.rst","position":55,"original_position":55,"commit_id":"f2e5dbbb6dae8646c73dd0c31cb17af99d948beb","original_commit_id":"f2e5dbbb6dae8646c73dd0c31cb17af99d948beb","user":{"login":"jbohren","id":1253450,"avatar_url":"https://avatars.githubusercontent.com/u/1253450?v=3","gravatar_id":"","url":"https://api.github.com/users/jbohren","html_url":"https://github.com/jbohren","followers_url":"https://api.github.com/users/jbohren/followers","following_url":"https://api.github.com/users/jbohren/following{/other_user}","gists_url":"https://api.github.com/users/jbohren/gists{/gist_id}","starred_url":"https://api.github.com/users/jbohren/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jbohren/subscriptions","organizations_url":"https://api.github.com/users/jbohren/orgs","repos_url":"https://api.github.com/users/jbohren/repos","events_url":"https://api.github.com/users/jbohren/events{/privacy}","received_events_url":"https://api.github.com/users/jbohren/received_events","type":"User","site_admin":false},"body":"Yeah, I expect that this behavior will change. I'll add a note in #283.","created_at":"2016-04-15T22:25:37Z","updated_at":"2016-04-15T22:25:37Z","html_url":"https://github.com/catkin/catkin_tools/pull/326#discussion_r59949693","pull_request_url":"https://api.github.com/repos/catkin/catkin_tools/pulls/326","_links":{"self":{"href":"https://api.github.com/repos/catkin/catkin_tools/pulls/comments/59949693"},"html":{"href":"https://github.com/catkin/catkin_tools/pull/326#discussion_r59949693"},"pull_request":{"href":"https://api.github.com/repos/catkin/catkin_tools/pulls/326"}}},"pull_request":{"url":"https://api.github.com/repos/catkin/catkin_tools/pulls/326","id":66709697,"html_url":"https://github.com/catkin/catkin_tools/pull/326","diff_url":"https://github.com/catkin/catkin_tools/pull/326.diff","patch_url":"https://github.com/catkin/catkin_tools/pull/326.patch","issue_url":"https://api.github.com/repos/catkin/catkin_tools/issues/326","number":326,"state":"open","locked":false,"title":"docs: Improving migration guide and adding a GitHub issue template","user":{"login":"jbohren","id":1253450,"avatar_url":"https://avatars.githubusercontent.com/u/1253450?v=3","gravatar_id":"","url":"https://api.github.com/users/jbohren","html_url":"https://github.com/jbohren","followers_url":"https://api.github.com/users/jbohren/followers","following_url":"https://api.github.com/users/jbohren/following{/other_user}","gists_url":"https://api.github.com/users/jbohren/gists{/gist_id}","starred_url":"https://api.github.com/users/jbohren/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jbohren/subscriptions","organizations_url":"https://api.github.com/users/jbohren/orgs","repos_url":"https://api.github.com/users/jbohren/repos","events_url":"https://api.github.com/users/jbohren/events{/privacy}","received_events_url":"https://api.github.com/users/jbohren/received_events","type":"User","site_admin":false},"body":"@dirk-thomas @jack-oquin What do you think about this modified migration guide and issue template?\r\n\r\n* Solution to #325 ","created_at":"2016-04-15T21:47:43Z","updated_at":"2016-04-15T22:25:37Z","closed_at":null,"merged_at":null,"merge_commit_sha":"63cceb626863a1506f53adb7ed4112e4147b13f9","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/catkin/catkin_tools/pulls/326/commits","review_comments_url":"https://api.github.com/repos/catkin/catkin_tools/pulls/326/comments","review_comment_url":"https://api.github.com/repos/catkin/catkin_tools/pulls/comments{/number}","comments_url":"https://api.github.com/repos/catkin/catkin_tools/issues/326/comments","statuses_url":"https://api.github.com/repos/catkin/catkin_tools/statuses/f2e5dbbb6dae8646c73dd0c31cb17af99d948beb","head":{"label":"catkin:new-migration-guide","ref":"new-migration-guide","sha":"f2e5dbbb6dae8646c73dd0c31cb17af99d948beb","user":{"login":"catkin","id":5697303,"avatar_url":"https://avatars.githubusercontent.com/u/5697303?v=3","gravatar_id":"","url":"https://api.github.com/users/catkin","html_url":"https://github.com/catkin","followers_url":"https://api.github.com/users/catkin/followers","following_url":"https://api.github.com/users/catkin/following{/other_user}","gists_url":"https://api.github.com/users/catkin/gists{/gist_id}","starred_url":"https://api.github.com/users/catkin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/catkin/subscriptions","organizations_url":"https://api.github.com/users/catkin/orgs","repos_url":"https://api.github.com/users/catkin/repos","events_url":"https://api.github.com/users/catkin/events{/privacy}","received_events_url":"https://api.github.com/users/catkin/received_events","type":"Organization","site_admin":false},"repo":{"id":17157565,"name":"catkin_tools","full_name":"catkin/catkin_tools","owner":{"login":"catkin","id":5697303,"avatar_url":"https://avatars.githubusercontent.com/u/5697303?v=3","gravatar_id":"","url":"https://api.github.com/users/catkin","html_url":"https://github.com/catkin","followers_url":"https://api.github.com/users/catkin/followers","following_url":"https://api.github.com/users/catkin/following{/other_user}","gists_url":"https://api.github.com/users/catkin/gists{/gist_id}","starred_url":"https://api.github.com/users/catkin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/catkin/subscriptions","organizations_url":"https://api.github.com/users/catkin/orgs","repos_url":"https://api.github.com/users/catkin/repos","events_url":"https://api.github.com/users/catkin/events{/privacy}","received_events_url":"https://api.github.com/users/catkin/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/catkin/catkin_tools","description":"Command line tools for working with catkin","fork":false,"url":"https://api.github.com/repos/catkin/catkin_tools","forks_url":"https://api.github.com/repos/catkin/catkin_tools/forks","keys_url":"https://api.github.com/repos/catkin/catkin_tools/keys{/key_id}","collaborators_url":"https://api.github.com/repos/catkin/catkin_tools/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/catkin/catkin_tools/teams","hooks_url":"https://api.github.com/repos/catkin/catkin_tools/hooks","issue_events_url":"https://api.github.com/repos/catkin/catkin_tools/issues/events{/number}","events_url":"https://api.github.com/repos/catkin/catkin_tools/events","assignees_url":"https://api.github.com/repos/catkin/catkin_tools/assignees{/user}","branches_url":"https://api.github.com/repos/catkin/catkin_tools/branches{/branch}","tags_url":"https://api.github.com/repos/catkin/catkin_tools/tags","blobs_url":"https://api.github.com/repos/catkin/catkin_tools/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/catkin/catkin_tools/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/catkin/catkin_tools/git/refs{/sha}","trees_url":"https://api.github.com/repos/catkin/catkin_tools/git/trees{/sha}","statuses_url":"https://api.github.com/repos/catkin/catkin_tools/statuses/{sha}","languages_url":"https://api.github.com/repos/catkin/catkin_tools/languages","stargazers_url":"https://api.github.com/repos/catkin/catkin_tools/stargazers","contributors_url":"https://api.github.com/repos/catkin/catkin_tools/contributors","subscribers_url":"https://api.github.com/repos/catkin/catkin_tools/subscribers","subscription_url":"https://api.github.com/repos/catkin/catkin_tools/subscription","commits_url":"https://api.github.com/repos/catkin/catkin_tools/commits{/sha}","git_commits_url":"https://api.github.com/repos/catkin/catkin_tools/git/commits{/sha}","comments_url":"https://api.github.com/repos/catkin/catkin_tools/comments{/number}","issue_comment_url":"https://api.github.com/repos/catkin/catkin_tools/issues/comments{/number}","contents_url":"https://api.github.com/repos/catkin/catkin_tools/contents/{+path}","compare_url":"https://api.github.com/repos/catkin/catkin_tools/compare/{base}...{head}","merges_url":"https://api.github.com/repos/catkin/catkin_tools/merges","archive_url":"https://api.github.com/repos/catkin/catkin_tools/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/catkin/catkin_tools/downloads","issues_url":"https://api.github.com/repos/catkin/catkin_tools/issues{/number}","pulls_url":"https://api.github.com/repos/catkin/catkin_tools/pulls{/number}","milestones_url":"https://api.github.com/repos/catkin/catkin_tools/milestones{/number}","notifications_url":"https://api.github.com/repos/catkin/catkin_tools/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/catkin/catkin_tools/labels{/name}","releases_url":"https://api.github.com/repos/catkin/catkin_tools/releases{/id}","deployments_url":"https://api.github.com/repos/catkin/catkin_tools/deployments","created_at":"2014-02-25T01:43:02Z","updated_at":"2016-03-23T11:23:51Z","pushed_at":"2016-04-15T22:15:05Z","git_url":"git://github.com/catkin/catkin_tools.git","ssh_url":"git@github.com:catkin/catkin_tools.git","clone_url":"https://github.com/catkin/catkin_tools.git","svn_url":"https://github.com/catkin/catkin_tools","homepage":null,"size":2039,"stargazers_count":25,"watchers_count":25,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":26,"mirror_url":null,"open_issues_count":53,"forks":26,"open_issues":53,"watchers":25,"default_branch":"master"}},"base":{"label":"catkin:master","ref":"master","sha":"ee2cf6916e66ca1f5885cb764b504e240e345517","user":{"login":"catkin","id":5697303,"avatar_url":"https://avatars.githubusercontent.com/u/5697303?v=3","gravatar_id":"","url":"https://api.github.com/users/catkin","html_url":"https://github.com/catkin","followers_url":"https://api.github.com/users/catkin/followers","following_url":"https://api.github.com/users/catkin/following{/other_user}","gists_url":"https://api.github.com/users/catkin/gists{/gist_id}","starred_url":"https://api.github.com/users/catkin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/catkin/subscriptions","organizations_url":"https://api.github.com/users/catkin/orgs","repos_url":"https://api.github.com/users/catkin/repos","events_url":"https://api.github.com/users/catkin/events{/privacy}","received_events_url":"https://api.github.com/users/catkin/received_events","type":"Organization","site_admin":false},"repo":{"id":17157565,"name":"catkin_tools","full_name":"catkin/catkin_tools","owner":{"login":"catkin","id":5697303,"avatar_url":"https://avatars.githubusercontent.com/u/5697303?v=3","gravatar_id":"","url":"https://api.github.com/users/catkin","html_url":"https://github.com/catkin","followers_url":"https://api.github.com/users/catkin/followers","following_url":"https://api.github.com/users/catkin/following{/other_user}","gists_url":"https://api.github.com/users/catkin/gists{/gist_id}","starred_url":"https://api.github.com/users/catkin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/catkin/subscriptions","organizations_url":"https://api.github.com/users/catkin/orgs","repos_url":"https://api.github.com/users/catkin/repos","events_url":"https://api.github.com/users/catkin/events{/privacy}","received_events_url":"https://api.github.com/users/catkin/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/catkin/catkin_tools","description":"Command line tools for working with catkin","fork":false,"url":"https://api.github.com/repos/catkin/catkin_tools","forks_url":"https://api.github.com/repos/catkin/catkin_tools/forks","keys_url":"https://api.github.com/repos/catkin/catkin_tools/keys{/key_id}","collaborators_url":"https://api.github.com/repos/catkin/catkin_tools/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/catkin/catkin_tools/teams","hooks_url":"https://api.github.com/repos/catkin/catkin_tools/hooks","issue_events_url":"https://api.github.com/repos/catkin/catkin_tools/issues/events{/number}","events_url":"https://api.github.com/repos/catkin/catkin_tools/events","assignees_url":"https://api.github.com/repos/catkin/catkin_tools/assignees{/user}","branches_url":"https://api.github.com/repos/catkin/catkin_tools/branches{/branch}","tags_url":"https://api.github.com/repos/catkin/catkin_tools/tags","blobs_url":"https://api.github.com/repos/catkin/catkin_tools/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/catkin/catkin_tools/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/catkin/catkin_tools/git/refs{/sha}","trees_url":"https://api.github.com/repos/catkin/catkin_tools/git/trees{/sha}","statuses_url":"https://api.github.com/repos/catkin/catkin_tools/statuses/{sha}","languages_url":"https://api.github.com/repos/catkin/catkin_tools/languages","stargazers_url":"https://api.github.com/repos/catkin/catkin_tools/stargazers","contributors_url":"https://api.github.com/repos/catkin/catkin_tools/contributors","subscribers_url":"https://api.github.com/repos/catkin/catkin_tools/subscribers","subscription_url":"https://api.github.com/repos/catkin/catkin_tools/subscription","commits_url":"https://api.github.com/repos/catkin/catkin_tools/commits{/sha}","git_commits_url":"https://api.github.com/repos/catkin/catkin_tools/git/commits{/sha}","comments_url":"https://api.github.com/repos/catkin/catkin_tools/comments{/number}","issue_comment_url":"https://api.github.com/repos/catkin/catkin_tools/issues/comments{/number}","contents_url":"https://api.github.com/repos/catkin/catkin_tools/contents/{+path}","compare_url":"https://api.github.com/repos/catkin/catkin_tools/compare/{base}...{head}","merges_url":"https://api.github.com/repos/catkin/catkin_tools/merges","archive_url":"https://api.github.com/repos/catkin/catkin_tools/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/catkin/catkin_tools/downloads","issues_url":"https://api.github.com/repos/catkin/catkin_tools/issues{/number}","pulls_url":"https://api.github.com/repos/catkin/catkin_tools/pulls{/number}","milestones_url":"https://api.github.com/repos/catkin/catkin_tools/milestones{/number}","notifications_url":"https://api.github.com/repos/catkin/catkin_tools/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/catkin/catkin_tools/labels{/name}","releases_url":"https://api.github.com/repos/catkin/catkin_tools/releases{/id}","deployments_url":"https://api.github.com/repos/catkin/catkin_tools/deployments","created_at":"2014-02-25T01:43:02Z","updated_at":"2016-03-23T11:23:51Z","pushed_at":"2016-04-15T22:15:05Z","git_url":"git://github.com/catkin/catkin_tools.git","ssh_url":"git@github.com:catkin/catkin_tools.git","clone_url":"https://github.com/catkin/catkin_tools.git","svn_url":"https://github.com/catkin/catkin_tools","homepage":null,"size":2039,"stargazers_count":25,"watchers_count":25,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":26,"mirror_url":null,"open_issues_count":53,"forks":26,"open_issues":53,"watchers":25,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/catkin/catkin_tools/pulls/326"},"html":{"href":"https://github.com/catkin/catkin_tools/pull/326"},"issue":{"href":"https://api.github.com/repos/catkin/catkin_tools/issues/326"},"comments":{"href":"https://api.github.com/repos/catkin/catkin_tools/issues/326/comments"},"review_comments":{"href":"https://api.github.com/repos/catkin/catkin_tools/pulls/326/comments"},"review_comment":{"href":"https://api.github.com/repos/catkin/catkin_tools/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/catkin/catkin_tools/pulls/326/commits"},"statuses":{"href":"https://api.github.com/repos/catkin/catkin_tools/statuses/f2e5dbbb6dae8646c73dd0c31cb17af99d948beb"}}}}