Skip to content

Commit faff9f1

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 faff9f1

File tree

1 file changed

+106
-113
lines changed

1 file changed

+106
-113
lines changed

‎docs/getting-help.rst‎

Lines changed: 106 additions & 113 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,13 +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:
87+
.. _getting-help-compile-time-label:
8188

82-
For run-time problems
83-
---------------------
89+
For problems building or installing Open MPI
90+
--------------------------------------------
8491

8592
Please provide *all* of the following information:
8693

@@ -95,78 +102,74 @@ Please provide *all* of the following information:
95102

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`` 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+
For example, you can use a sequence of commands similar to the
114+
following (adjust as necessary for your specific environment):
120115

121-
shell$ mpirun --map-by node --hostfile my_hostfile.txt --output tag ompi_info --version
116+
.. code-block:: sh
122117
118+
# Make a directory for the output files, then build/install Open MPI
119+
shell$ mkdir ompi-output
120+
shell$ ./configure {options} 2>&1 | tee ompi-output/config.out
121+
shell$ tar cf - `find . -name config.log` | tar -C ompi-output -x -
122+
shell$ make all 2>&1 | tee ompi-output/make.out
123+
shell$ make install 2>&1 | tee ompi-output/make-install.out
123124
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:
125+
# Bundle up all of these files into a tarball
126+
shell$ tar jcf ompi-output.tar.bz2 ompi-output
129127
130-
.. code-block:: sh
128+
Then attach the resulting ``ompi-output.tar.bz2`` file to your report.
131129

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
130+
.. caution:: As mentioned above, the Open MPI mailing lists **limit
131+
each message to a maximum of 150 KB.** If attaching the tarball
132+
makes your message larger than 150 KB, you may need to post the
133+
tarball elsewhere and include a link to that tarball in your mail
134+
to the list.
138135

139-
.. code-block:: sh
136+
.. _getting-help-run-time-label:
140137

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
138+
For problems launching or running MPI applications
139+
--------------------------------------------------
146140

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:
141+
Please provide *all* of the following information:
154142

155-
* The exact command used to run your application.
143+
.. important:: The more information you include in your report, the
144+
better. E-mails/bug reports simply stating, "It doesn't work!"
145+
are not helpful; we need to know as much information about your
146+
environment as possible in order to provide meaningful assistance.
156147

157-
* Any relevant MCA parameters that were set (or unset) when
158-
you ran (from either the command line, environment,
159-
parameter file, etc.).
148+
**The best way to get help** is to provide a "recipe" for
149+
reproducing the problem. This will allow the Open MPI developers
150+
to see the error for themselves, and therefore be able to fix it.
160151

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).
152+
#. The version of Open MPI that you're using.
166153

167-
#. Detailed information about your network:
154+
#. The stdout and stderr from running ``configure``.
168155

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

171174
#. For RoCE- or InfiniBand-based networks, include the information
172175
:ref:`in this FAQ entry <faq-ib-troubleshoot-label>`.
@@ -179,62 +182,52 @@ Please provide *all* of the following information:
179182
``ifconfig`` in the default ``PATH`` of normal users.
180183
Try looking for it in ``/sbin`` or ``/usr/sbin``.
181184

182-
.. _getting-help-compile-time-label:
183-
184-
For compile problems
185-
--------------------
186-
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).
185+
#. A *detailed* description of what is failing. *The more details
186+
that you provide, the better.* Please include at least the
187+
following information:
202188

203-
#. Output from when you ran ``./configure`` to configure Open MPI
204-
(**compress or post to a GitHub gist or Pastebin!**).
189+
* The exact command used to run your application.
205190

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

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

212-
#. Output from when you ran ``make install`` to install Open MPI
213-
(**compress or post to a GitHub gist or Pastebin!**).
201+
For example, you can use a sequence of commands similar to the
202+
following (adjust as necessary for your specific environment):
214203

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:
204+
.. code:: sh
219205
220-
.. code-block:: sh
206+
# Make a directory for the output files, then build/install Open MPI
207+
shell$ mkdir ompi-output
208+
shell$ ./configure {options} 2>&1 | tee ompi-output/config.out
209+
shell$ tar cf - `find . -name config.log` | tar -C ompi-output -x -
210+
shell$ make all 2>&1 | tee ompi-output/make-all.out
211+
shell$ make install 2>&1 | tee ompi-output/make-install.out
221212
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
213+
# Get installation and system information
214+
shell$ ompi_info --all 2>&1 | tee ompi-output/ompi-info-all.out
215+
shell$ lstopo -v | tee ompi-output/lstopo-v.out
229216
230-
.. code-block:: sh
217+
# Have a text file "my_hostfile.txt" with the hostnames on which
218+
# you are trying to launch
219+
shell$ for host in `cat my_hostfile.txt`; do
220+
> ssh $host ompi_info --version 2>&1 | tee `pwd`/ompi-output/ompi_info-version-$host.out
221+
> ssh $host lstopo -v | tee `pwd`/ompi-output/lstopo-v-$host.out
222+
> done
231223
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
224+
# Bundle up all of these files into a tarball
225+
shell$ tar jcf ompi-output.tar.bz2 ompi-output
239226
240227
Then attach the resulting ``ompi-output.tar.bz2`` file to your report.
228+
229+
.. caution:: As mentioned above, the Open MPI mailing lists **limit
230+
each message to a maximum of 150 KB.** If attaching the tarball
231+
makes your message larger than 150 KB, you may need to post the
232+
tarball elsewhere and include a link to that tarball in your mail
233+
to the list.

0 commit comments

Comments
 (0)