search

ros2 / ros2_documentation

ROS 2 docs repository
https://docs.ros.org/en/rolling
Creative Commons Attribution 4.0 International
532 stars 1.05k forks source link

Add general install instructions #305

Open maryaB-osr opened 5 years ago

maryaB-osr commented 5 years ago

General install instructions for people who don't use any of the listed platforms. I'd appreciate some notes on the technical steps, or discussion on the best way to do this or if it's relevant.

nuclearsandwich commented 5 years ago

What are you expecting readers would gain from such instructions? To provide and maintain general installation instructions that are sufficient to install and use ROS is a substantial maintenance burden. Scoping that burden is one of the reasons we have a limited number of supported platforms.

If your suggestion is just to add that platforms not listed are unsupported and link to community resources for getting help then I think that could be reviewed but I don't think we can provide instructions with sufficient technical detail to be useful and still be general enough to apply to any platform a reader may wish to use.

maryaB-osr commented 5 years ago

I was considering the common threads between the different platform installation instructions, like "install dependencies", "get ros2 code", "build the code", etc. I thought maybe a general explanation of those things would be a good start for some users to understand what they needed to do and maybe scope out the resources for their own platform themselves. But, if you think that'd be way too general to provide and real benefit, then maybe it falls under "not relevant".

dirk-thomas commented 5 years ago

General install instructions would be valuable imo. They can capture the high level steps for users to adapt them to their platform which doesn't have specific instructions as well as capture global constraints like dependency A needs at least version X. Additionally it can describe the many platform independent aspects:

I see the instructions for each supported platform as a specialization of the generic steps. This would be the instructions which would be updated first on changes.

jacobperron commented 5 years ago

I've thrown together a rough outline using MacOSX Installation as a reference, hopefully it's helpful:

  1. Install prerequisites, I haven't done it here, but it's probably worth adding minimum version numbers and links to web listings:

    • Python 3
    • tinyxml
    • eigen
    • pcre
    • poco
    • console_bridge
    • log4cxx
    • catkin_pkg
    • empy
    • lark-parser
    • lxml
    • numpy
    • pyparsing
    • pyyaml
    • setuptools
    • argcomplete
    • Fast-RTPS dependencies:
      • asio
      • tinyxml2
    • Secure ROS 2 dependencies:
      • OpenSSL
    • Visualization dependencies:
      • Qt 5
      • pyqt5
      • freetype
      • assimp
      • graphviz
      • pygraphviz
      • pydot
    • Demos dependencies:
      • opencv

  2. Get ROS 2

    • Get a tagged release (recommended) as binaries or build from source.
    • If contributing to the core ROS 2 packages, checkout the latest development branches found in the ros2.repos file in the ros2/ros2 repo.
    • If contributing to a past release (e.g. bug fixes), use the appropriate branch of ros2/ros2, e.g.:

  3. About RMW implementations

    • Perhaps here it's worth explaining in this section:
      • What an RMW implementation is
      • The default implementation(s) available
      • How to use a particular RMW implementation
      • Maybe a list of community contributed implementations
    • Here's an existing turtorial with information. We probably don't need to duplicate the information, so maybe we could just link to the tutorial from the general installation instructions (or merge the articles).

  4. Run demos

    • To confirm that the installation was successful, we could provide some info on running the talker/listener demo.
    • Sourcing the installation is a required step and varies per platform/installation method, so I'm not sure how best to document this.
dirk-thomas commented 5 years ago

Install prerequisites

This list highly depends on what packages you are trying to build. Imo the generic instructions shouldn't enumerate them in full since many are only relevant if you want to build specific packages like image_common, rqt etc.

Instead I would focus on the dependencies of "core" packages and mention that additional packages might require additional dependencies.

jacobperron commented 5 years ago

Instead I would focus on the dependencies of "core" packages and mention that additional packages might require additional dependencies.

Makes sense. I tried to do that by adding sub-headers like "Visualization dependencies", but it might be the case we can slim down the following list for "core" packages: