Skip to content

Commit 4feb02b

Browse files
jsquyresjsquyres
committed
docs: update "Getting help"
Revamp the "Getting help" docs page to include a bit more information and have more recent procedures for the Open MPI community. Signed-off-by: Jeff Squyres <[email protected]>
1 parent dd7cbdd commit 4feb02b

File tree

1 file changed

+112
-115
lines changed

1 file changed

+112
-115
lines changed

‎docs/getting-help.rst‎

Lines changed: 112 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -36,15 +36,18 @@ places. If you have:
3636
there.
3737

3838
.. note:: Because of spam, only subscribers to the mailing list are
39-
allowed to post to the mailing list. Specifically: you must
40-
subscribe to the mailing list before posting.
39+
allowed to post to the mailing list. Specifically: **you must
40+
subscribe to the mailing list before posting.**
4141

42-
* If you have a run-time question or problem, see the :ref:`For
43-
run-time problems <getting-help-run-time-label>` section below for
44-
the content of what to include in your email.
4542
* If you have a compile-time question or problem, see the :ref:`For
46-
compile-time problems <getting-help-compile-time-label>` section
47-
below for the content of what to include in your email.
43+
problems building or installing Open MPI
44+
<getting-help-compile-time-label>` section below for the content
45+
of what to include in your email.
46+
47+
* If you have a run-time question or problem, see the :ref:`For
48+
problems launching or running MPI applications
49+
<getting-help-run-time-label>` section below for the content of
50+
what to include in your email.
4851

4952
.. note:: The mailing lists have **a 150 KB size limit on
5053
messages** (this is a limitation of the mailing list web
@@ -74,15 +77,17 @@ places. If you have:
7477
<https://www.open-mpi.org/community/lists/ompi.php>`_ and post it
7578
there.
7679

80+
.. note:: Just like the user's mailing list (see above), **you must
81+
subscribe to the mailing list before posting,** and **posts are
82+
limited to 150 KB.**
83+
7784
If you're unsure where to send your question, subscribe and send an
7885
email to the user's mailing list.
7986

80-
.. _getting-help-run-time-label:
81-
82-
For run-time problems
83-
---------------------
87+
.. _getting-help-compile-time-label:
8488

85-
Please provide *all* of the following information:
89+
For problems building or installing Open MPI
90+
--------------------------------------------
8691

8792
.. important:: The more information you include in your report, the
8893
better. E-mails/bug reports simply stating, "It doesn't work!"
@@ -93,148 +98,140 @@ Please provide *all* of the following information:
9398
reproducing the problem. This will allow the Open MPI developers
9499
to see the error for themselves, and therefore be able to fix it.
95100

101+
Please provide *all* of the following information:
102+
96103
#. The version of Open MPI that you're using.
97104

98-
#. The ``config.log`` file from the top-level Open MPI directory, if
99-
available (**compress or post to a Github gist or Pastebin**).
105+
#. The stdout and stderr from running ``configure``.
100106

101-
#. The output of the ``ompi_info --all`` command from the node where
102-
you're invoking ``mpirun``.
107+
#. All ``config.log`` files from the Open MPI build tree.
103108

104-
#. If you have questions or problems about process affinity /
105-
binding, send the output from running the ``lstopo -v``
106-
command from a recent version of `Hwloc
107-
<https://www.open-mpi.org/projects/hwloc/>`_. *The detailed
108-
text output is preferable to a graphical output.*
109+
#. Output from when you ran ``make V=1 all`` to build Open MPI.
109110

110-
#. If running on more than one node |mdash| especially if you're
111-
having problems launching Open MPI processes |mdash| also include
112-
the output of the ``ompi_info --version`` command **from each node
113-
on which you're trying to run**.
111+
#. Output from when you ran ``make install`` to install Open MPI.
114112

115-
#. If you are able to launch MPI processes, you can use
116-
``mpirun`` to gather this information. For example, if
117-
the file ``my_hostfile.txt`` contains the hostnames of the
118-
machines on which you are trying to run Open MPI
119-
processes::
113+
You can use a sequence of commands similar to the following to gather
114+
much of the above information (adjust as necessary for your specific
115+
environment):
120116

121-
shell$ mpirun --map-by node --hostfile my_hostfile.txt --output tag ompi_info --version
117+
.. code-block:: sh
122118
119+
# Make a directory for the output files, then build/install Open MPI
120+
shell$ mkdir ompi-output
121+
shell$ ./configure {options} 2>&1 | tee ompi-output/config.out
122+
shell$ tar cf - `find . -name config.log` | tar -C ompi-output -x -
123+
shell$ make V=1 all 2>&1 | tee ompi-output/make.out
124+
shell$ make install 2>&1 | tee ompi-output/make-install.out
123125
124-
#. If you cannot launch MPI processes, use some other mechanism
125-
|mdash| such as ``ssh`` |mdash| to gather this information. For
126-
example, if the file ``my_hostfile.txt`` contains the hostnames
127-
of the machines on which you are trying to run Open MPI
128-
processes:
126+
# Bundle up all of these files into a tarball
127+
shell$ tar jcf ompi-output.tar.bz2 ompi-output
129128
130-
.. code-block:: sh
129+
Then attach the resulting ``ompi-output.tar.bz2`` file to your report.
131130

132-
# Bourne-style shell (e.g., bash, zsh, sh)
133-
shell$ for h in `cat my_hostfile.txt`
134-
> do
135-
> echo "=== Hostname: $h"
136-
> ssh $h ompi_info --version
137-
> done
131+
.. caution:: As mentioned above, the Open MPI mailing lists **limit
132+
each message to a maximum of 150 KB.** If attaching the tarball
133+
makes your message larger than 150 KB, you may need to post the
134+
tarball elsewhere and include a link to that tarball in your mail
135+
to the list.
138136

139-
.. code-block:: sh
137+
.. _getting-help-run-time-label:
140138

141-
# C-style shell (e.g., csh, tcsh)
142-
shell% foreach h (`cat my_hostfile.txt`)
143-
foreach? echo "=== Hostname: $h"
144-
foreach? ssh $h ompi_info --version
145-
foreach? end
139+
For problems launching or running MPI applications
140+
--------------------------------------------------
146141

147-
#. A *detailed* description of what is failing. The more
148-
details that you provide, the better. E-mails saying "My
149-
application doesn't work!" will inevitably be answered with
150-
requests for more information about *exactly what doesn't
151-
work*; so please include as much information detailed in your
152-
initial e-mail as possible. We strongly recommend that you
153-
include the following information:
142+
.. important:: The more information you include in your report, the
143+
better. E-mails/bug reports simply stating, "It doesn't work!"
144+
are not helpful; we need to know as much information about your
145+
environment as possible in order to provide meaningful assistance.
154146

155-
* The exact command used to run your application.
147+
**The best way to get help** is to provide a "recipe" for
148+
reproducing the problem. This will allow the Open MPI developers
149+
to see the error for themselves, and therefore be able to fix it.
156150

157-
* Any relevant MCA parameters that were set (or unset) when
158-
you ran (from either the command line, environment,
159-
parameter file, etc.).
151+
Please provide *all* of the following information:
160152

161-
* The value of the ``PATH`` and ``LD_LIBRARY_PATH``
162-
environment variables (did you set them correctly to point
163-
to all relevant executables, the Open MPI libraries, and
164-
any required support libraries, such as libraries required
165-
for high-speed networks such as InfiniBand).
153+
#. The version of Open MPI that you're using.
154+
155+
#. The stdout and stderr from running ``configure``.
166156

167-
#. Detailed information about your network:
157+
#. All ``config.log`` files from the Open MPI build tree.
158+
159+
#. If you have questions or problems about process affinity /
160+
binding, send the output from running the ``lstopo -v``
161+
command from a recent version of `Hwloc
162+
<https://www.open-mpi.org/projects/hwloc/>`_. *The detailed
163+
text output is preferable to a graphical output.*
164+
165+
#. The output of the ``ompi_info --all`` command from the node where
166+
you're invoking ``mpirun``.
167+
168+
#. If running on more than one node |mdash| especially if you're
169+
having problems launching Open MPI processes |mdash| also include
170+
the output of the ``ompi_info --version`` command **from each node
171+
on which you're trying to run**.
172+
173+
#. Detailed information about your network.
168174

169175
.. error:: TODO Update link to IB FAQ entry.
170176

171177
#. For RoCE- or InfiniBand-based networks, include the information
172178
:ref:`in this FAQ entry <faq-ib-troubleshoot-label>`.
173179

174-
#. For Ethernet-based networks (including RoCE-based networks,
180+
#. For Ethernet-based networks (including RoCE-based networks),
175181
include the output of the ``ip addr`` command (or the legacy
176182
``ifconfig`` command) on all relevant nodes.
177183

178184
.. note:: Some Linux distributions do not put ``ip`` or
179185
``ifconfig`` in the default ``PATH`` of normal users.
180186
Try looking for it in ``/sbin`` or ``/usr/sbin``.
181187

182-
.. _getting-help-compile-time-label:
183-
184-
For compile problems
185-
--------------------
188+
#. A *detailed* description of what is failing. *The more details
189+
that you provide, the better.* Please include at least the
190+
following information:
186191

187-
Please provide *all* of the following information:
188-
189-
.. important:: The more information you include in your report, the
190-
better. E-mails/bug reports simply stating, "It doesn't work!"
191-
are not helpful; we need to know as much information about your
192-
environment as possible in order to provide meaningful assistance.
193-
194-
**The best way to get help** is to provide a "recipe" for
195-
reproducing the problem. This will allow the Open MPI developers
196-
to see the error for themselves, and therefore be able to fix it.
197-
198-
#. The version of Open MPI that you're using.
199-
200-
#. All output (both compilation output and run time output, including
201-
all error messages).
202-
203-
#. Output from when you ran ``./configure`` to configure Open MPI
204-
(**compress or post to a GitHub gist or Pastebin!**).
192+
* The exact command used to run your application.
205193

206-
#. The ``config.log`` file from the top-level Open MPI directory
207-
(**compress or post to a GitHub gist or Pastebin!**).
194+
* Any relevant MCA parameters that were set (or unset) when
195+
you ran (from either the command line, environment,
196+
parameter file, etc.).
208197

209-
#. Output from when you ran ``make V=1`` to build Open MPI (**compress
210-
or post to a GitHub gist or Pastebin!**).
198+
* The value of the ``PATH`` and ``LD_LIBRARY_PATH``
199+
environment variables (did you set them correctly to point
200+
to all relevant executables, the Open MPI libraries, and
201+
any required support libraries, such as libraries required
202+
for high-speed networks such as InfiniBand).
211203

212-
#. Output from when you ran ``make install`` to install Open MPI
213-
(**compress or post to a GitHub gist or Pastebin!**).
204+
You can use a sequence of commands similar to the following to gather
205+
much of the above information (adjust as necessary for your specific
206+
environment):
214207

215-
To capture the output of the configure and make steps, you can use the
216-
script command or the following technique to capture all the files in
217-
a unique directory, suitable for tarring and compressing into a single
218-
file:
208+
.. code:: sh
219209
220-
.. code-block:: sh
210+
# Make a directory for the output files, then build/install Open MPI
211+
shell$ mkdir ompi-output
212+
shell$ ./configure {options} 2>&1 | tee ompi-output/config.out
213+
shell$ tar cf - `find . -name config.log` | tar -C ompi-output -x -
214+
shell$ make all 2>&1 | tee ompi-output/make-all.out
215+
shell$ make install 2>&1 | tee ompi-output/make-install.out
221216
222-
# Bourne-style shell (e.g., bash, zsh, sh)
223-
shell$ mkdir $HOME/ompi-output
224-
shell$ ./configure {options} 2>&1 | tee $HOME/ompi-output/config.out
225-
shell$ make all 2>&1 | tee $HOME/ompi-output/make.out
226-
shell$ make install 2>&1 | tee $HOME/ompi-output/make-install.out
227-
shell$ cd $HOME
228-
shell$ tar jcvf ompi-output.tar.bz2 ompi-output
217+
# Get installation and system information
218+
shell$ ompi_info --all 2>&1 | tee ompi-output/ompi-info-all.out
219+
shell$ lstopo -v | tee ompi-output/lstopo-v.out
229220
230-
.. code-block:: sh
221+
# Have a text file "my_hostfile.txt" with the hostnames on which
222+
# you are trying to launch
223+
shell$ for host in `cat my_hostfile.txt`; do
224+
> ssh $host ompi_info --version 2>&1 | tee `pwd`/ompi-output/ompi_info-version-$host.out
225+
> ssh $host lstopo -v | tee `pwd`/ompi-output/lstopo-v-$host.out
226+
> done
231227
232-
# C-style shell (e.g., csh, tcsh)
233-
shell% mkdir $HOME/ompi-output
234-
shell% ./configure {options} |& tee $HOME/ompi-output/config.out
235-
shell% make all |& tee $HOME/ompi-output/make.out
236-
shell% make install |& tee $HOME/ompi-output/make-install.out
237-
shell% cd $HOME
238-
shell% tar jcvf ompi-output.tar.bz2 ompi-output
228+
# Bundle up all of these files into a tarball
229+
shell$ tar jcf ompi-output.tar.bz2 ompi-output
239230
240231
Then attach the resulting ``ompi-output.tar.bz2`` file to your report.
232+
233+
.. caution:: As mentioned above, the Open MPI mailing lists **limit
234+
each message to a maximum of 150 KB.** If attaching the tarball
235+
makes your message larger than 150 KB, you may need to post the
236+
tarball elsewhere and include a link to that tarball in your mail
237+
to the list.

0 commit comments

Comments
 (0)