Skip to content

Commit 9afe586

Browse files
jsquyresjsquyres
authored
Merge pull request #7600 from jsquyres/pr/mpit-general-docs
MPI_T general docs
2 parents 698e6bb + de22f84 commit 9afe586

20 files changed

+1061
-743
lines changed

‎HACKING

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,3 +247,26 @@ If you do not have Flex installed, it can be downloaded from the
247247
following URL:
248248

249249
https://github.com/westes/flex
250+
251+
Use of Pandoc
252+
=============
253+
254+
Similar to prior sections, you need to read/care about this section
255+
*ONLY* if you are building from a developer's tree (i.e., a Git clone
256+
of the Open MPI source tree). If you have an Open MPI distribution
257+
tarball, the contents of this section are optional -- you can (and
258+
probably should) skip reading this section.
259+
260+
The Pandoc tool is used to generate Open MPI's man pages.
261+
Specifically: Open MPI's man pages are written in Markdown; Pandoc is
262+
the tool that converts that Markdown to nroff (i.e., the format of man
263+
pages).
264+
265+
You must have Pandoc >=v1.12 when building Open MPI from a developer's
266+
tree. If configure cannot find Pandoc >=v1.12, it will abort.
267+
268+
If you need to install Pandoc, check your operating system-provided
269+
packages (to include MacOS Homebrew and MacPorts). The Pandoc project
270+
itself also offers binaries for their releases:
271+
272+
https://pandoc.org/

‎Makefile.ompi-rules

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
# $HEADER$
1010
#
1111

12+
MD2NROFF = $(OMPI_TOP_SRCDIR)/config/md2nroff.pl
13+
1214
TRIM_OPTIONS=
1315
if ! MAN_PAGE_BUILD_MPIFH_BINDINGS
1416
TRIM_OPTIONS += --nofortran
@@ -17,6 +19,8 @@ if ! MAN_PAGE_BUILD_USEMPIF08_BINDINGS
1719
TRIM_OPTIONS += --nof08
1820
endif
1921

22+
# JMS This rule can be deleted once all man pages have been converted
23+
# to markdown.
2024
.1in.1:
2125
$(OMPI_V_GEN) $(top_srcdir)/config/make_manpage.pl \
2226
--package-name='@PACKAGE_NAME@' \
@@ -26,6 +30,8 @@ endif
2630
--input=$< \
2731
--output=$@
2832

33+
# JMS This rule can be deleted once all man pages have been converted
34+
# to markdown.
2935
.3in.3:
3036
$(OMPI_V_GEN) $(top_srcdir)/config/make_manpage.pl \
3137
--package-name='@PACKAGE_NAME@' \
@@ -36,6 +42,8 @@ endif
3642
--input=$< \
3743
--output=$@
3844

45+
# JMS This rule can be deleted once all man pages have been converted
46+
# to markdown.
3947
.7in.7:
4048
$(OMPI_V_GEN) $(top_srcdir)/config/make_manpage.pl \
4149
--package-name='@PACKAGE_NAME@' \
@@ -45,6 +53,28 @@ endif
4553
--input=$< \
4654
--output=$@
4755

56+
%.1: %.1.md
57+
$(OMPI_V_GEN) $(MD2NROFF) --source=$< --dest=$@ --pandoc=$(PANDOC)
58+
59+
%.3: %.3.md
60+
$(OMPI_V_GEN) $(MD2NROFF) --source=$< --dest=$@ --pandoc=$(PANDOC)
61+
62+
%.5: %.5.md
63+
$(OMPI_V_GEN) $(MD2NROFF) --source=$< --dest=$@ --pandoc=$(PANDOC)
64+
65+
%.7: %.7.md
66+
$(OMPI_V_GEN) $(MD2NROFF) --source=$< --dest=$@ --pandoc=$(PANDOC)
67+
68+
# It is an error to "configure --disable-man-pages" and then try to
69+
# "make dist".
70+
if !OPAL_ENABLE_MAN_PAGES
71+
dist-hook:
72+
@echo "************************************************************************************"
73+
@echo "ERROR: 'make dist' inoperable when Open MPI is configured with --disable-man-pages"
74+
@echo "************************************************************************************"
75+
@/bin/false
76+
endif
77+
4878
# A little verbosity magic; "make" will show the terse output. "make
4979
# V=1" will show the actual commands used (just like the other
5080
# Automake-generated compilation/linker rules).

‎config/Makefile.am

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@ EXTRA_DIST = \
2929
ltmain_pgi_tp.diff \
3030
opal_mca_priority_sort.pl \
3131
find_common_syms \
32-
make_manpage.pl
32+
make_manpage.pl \
33+
md2nroff.pl
3334

3435
maintainer-clean-local:
3536
rm -f opal_get_version.sh

‎config/md2nroff.pl

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
#!/usr/bin/env perl
2+
#
3+
# Copyright (c) 2020 Cisco Systems, Inc. All rights reserved.
4+
# $COPYRIGHT$
5+
#
6+
# Additional copyrights may follow
7+
#
8+
# $HEADER$
9+
#
10+
11+
use strict;
12+
13+
use IPC::Open3;
14+
use File::Basename;
15+
use Getopt::Long;
16+
17+
#--------------------------------------------------------------------------
18+
19+
my $source_arg;
20+
my $dest_arg;
21+
my $pandoc_arg = "pandoc";
22+
my $help_arg;
23+
my $verbose_arg;
24+
25+
my $ok = Getopt::Long::GetOptions("source=s" => \$source_arg,
26+
"dest=s" => \$dest_arg,
27+
"pandoc=s" => \$pandoc_arg,
28+
"help" => \$help_arg,
29+
"verbose" => \$verbose_arg);
30+
31+
if (!$source_arg || !$dest_arg) {
32+
print("Must specify --source and --dest\n");
33+
$ok = 0;
34+
}
35+
36+
if (!$ok || $help_arg) {
37+
print "Invalid command line argument.\n\n"
38+
if (!$ok);
39+
print "Options:
40+
--source FILE Source Markdown filename
41+
--dest FILE Destination nroff file
42+
--pandoc FILE Location of pandoc executable
43+
--help This help list
44+
--verbose Be verbose when running\n";
45+
exit($ok ? 0 : 1);
46+
}
47+
48+
#--------------------------------------------------------------------------
49+
50+
# Read in the source
51+
die "Error: $source_arg does not exist"
52+
if (! -f $source_arg);
53+
54+
my $source_content;
55+
open(FILE, $source_arg) ||
56+
die "Can't open $source_arg";
57+
$source_content .= $_
58+
while(<FILE>);
59+
close(FILE);
60+
61+
#--------------------------------------------------------------------------
62+
63+
# Figure out the section of man page
64+
die "Cannot figure out man page section from source filename"
65+
if (!($source_arg =~ m/(\d+).md$/));
66+
my $man_section = $1;
67+
68+
my $shortfile = basename($source_arg);
69+
$shortfile =~ s/\.$man_section\.md$//;
70+
71+
#--------------------------------------------------------------------------
72+
73+
my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime();
74+
my $today = sprintf("%04d-%02d-%02d", ($year+1900), $mon, $mday);
75+
76+
# Run opal_get_version.sh to get the OMPI version.
77+
my $config_dir = dirname($0);
78+
my $get_version = "$config_dir/opal_get_version.sh";
79+
my $VERSION_file = "$config_dir/../VERSION";
80+
my $out = `$get_version $VERSION_file --full`;
81+
chomp($out);
82+
83+
# Pandoc does not handle markdown links in output nroff properly, so
84+
# just remove all links. Specifically: some versions of Pandoc ignore
85+
# the links, but others handle it badly.
86+
$source_content =~ s/\[(.+)\]\((.+)\)/\1/g;
87+
88+
# Add the pandoc header
89+
$source_content = "---
90+
section: $man_section
91+
title: $shortfile
92+
header: Open MPI
93+
footer: $today
94+
---
95+
96+
$source_content";
97+
98+
#--------------------------------------------------------------------------
99+
100+
print("*** Processing: $source_arg --> $dest_arg\n")
101+
if ($verbose_arg);
102+
103+
my $pid = open3(my $child_stdin, my $child_stdout, my $child_stderr,
104+
"$pandoc_arg -s --from=markdown --to=man");
105+
print $child_stdin $source_content;
106+
close($child_stdin);
107+
my $pandoc_rendered;
108+
$pandoc_rendered .= $_
109+
while(<$child_stdout>);
110+
close($child_stdout);
111+
close($child_stderr)
112+
if ($child_stderr);
113+
waitpid($pid, 0);
114+
115+
print("Writing new file $dest_arg\n")
116+
if ($verbose_arg);
117+
118+
# Make the target directory if it does not exist (needed for VPATH
119+
# builds)
120+
my $dest_dir = dirname($dest_arg);
121+
mkdir($dest_dir)
122+
if (! -d $dest_dir);
123+
124+
# Write the output file
125+
open(FILE, ">$dest_arg") ||
126+
die "Can't open $dest_arg for writing";
127+
print FILE $pandoc_rendered;
128+
close(FILE);
129+
130+
exit(0);

‎config/ompi_config_files.m4

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,9 @@ AC_DEFUN([OMPI_CONFIG_FILES],[
4545
ompi/mpi/tool/Makefile
4646
ompi/mpi/tool/profile/Makefile
4747

48+
ompi/mpi/man/man3/Makefile
49+
ompi/mpi/man/man5/Makefile
50+
4851
ompi/tools/ompi_info/Makefile
4952
ompi/tools/wrappers/Makefile
5053
ompi/tools/wrappers/mpicc-wrapper-data.txt

‎config/opal_setup_man_pages.m4

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
dnl -*- shell-script -*-
2+
dnl
3+
dnl Copyright (c) 2020 Cisco Systems, Inc. All rights reserved.
4+
dnl
5+
dnl $COPYRIGHT$
6+
dnl
7+
dnl Additional copyrights may follow
8+
dnl
9+
dnl $HEADER$
10+
dnl
11+
12+
dnl
13+
dnl Just in case someone looks for it here someday, here is a
14+
dnl conveninent reference for what Markdown pandoc supports:
15+
dnl
16+
dnl https://rmarkdown.rstudio.com/authoring_pandoc_markdown.html
17+
dnl
18+
19+
AC_DEFUN([OPAL_SETUP_MAN_PAGES],[
20+
AC_ARG_ENABLE(man-pages,
21+
[AC_HELP_STRING([--disable-man-pages],
22+
[Do not generate/install man pages (default: enable)])])
23+
24+
PANDOC=
25+
OPAL_ENABLE_MAN_PAGES=0
26+
AC_MSG_CHECKING([if want man pages])
27+
AS_IF([test -z "$enable_man_pages" || test "$enable_man_pages" = "yes"],
28+
[AC_MSG_RESULT([yes])
29+
OPAL_ENABLE_MAN_PAGES=1
30+
_OPAL_SETUP_PANDOC],
31+
[AC_MSG_RESULT([no])])
32+
33+
AC_SUBST(PANDOC)
34+
AM_CONDITIONAL([OPAL_ENABLE_MAN_PAGES], [test $OPAL_ENABLE_MAN_PAGES -eq 1])
35+
])
36+
37+
dnl Back-end pandoc setup
38+
AC_DEFUN([_OPAL_SETUP_PANDOC],[
39+
OPAL_VAR_SCOPE_PUSH([min_major_version min_minor_version pandoc_version pandoc_major pandoc_minor])
40+
41+
# If we need to generate man pages, we need pandoc >v1.12.
42+
AC_PATH_PROG([PANDOC], [pandoc])
43+
44+
# If we found Pandoc, check its version. We need >=v1.12.
45+
# To be clear: I know that v1.12 works, and I know that v1.9 does not
46+
# work. I did not test the versions in between to know exactly what
47+
# the lowest version is that works. Someone is free to update this
48+
# check someday to be more accurate if they wish.
49+
min_major_version=1
50+
min_minor_version=12
51+
AS_IF([test -n "$PANDOC"],
52+
[pandoc_version=`pandoc --version | head -n 1 | awk '{ print $[2] }'`
53+
pandoc_major=`echo $pandoc_version | cut -d\. -f1`
54+
pandoc_minor=`echo $pandoc_version | cut -d\. -f2`
55+
AC_MSG_CHECKING([pandoc version])
56+
AC_MSG_RESULT([major: $pandoc_major, minor: $pandoc_minor])
57+
58+
AC_MSG_CHECKING([if pandoc version is >=v$min_major_version.$min_minor_version])
59+
AS_IF([test $pandoc_major -lt $min_major_version], [PANDOC=])
60+
AS_IF([test $pandoc_major -eq $min_major_version && test $pandoc_minor -lt $min_minor_version],
61+
[PANDOC=])
62+
AS_IF([test -n "$PANDOC"],
63+
[AC_MSG_RESULT([yes])],
64+
[AC_MSG_RESULT([no])])
65+
])
66+
67+
AS_IF([test -z "$PANDOC" || test -n "`echo $PANDOC | $GREP missing`"],
68+
[AS_IF([test ! -f "$srcdir/ompi/mpi/man/man5/MPI_T.5"],
69+
[AC_MSG_WARN([*** Could not find a suitable pandoc on your system.])
70+
AC_MSG_WARN([*** You need pandoc >=$min_major_version.$min_minor_version to build Open MPI man pages.])
71+
AC_MSG_WARN([*** See pandoc.org.])
72+
AC_MSG_WARN([*** NOTE: If you are building from a tarball downloaded from www.open-mpi.org, you do not need Pandoc])
73+
AC_MSG_ERROR([Cannot continue])
74+
])
75+
])
76+
77+
OPAL_VAR_SCOPE_POP
78+
])

‎configure.ac

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -70,13 +70,14 @@ OPAL_LOAD_PLATFORM
7070
# Start it up
7171
#
7272

73+
OPAL_CONFIGURE_SETUP
74+
opal_show_title "Configuring project_name_long"
75+
opal_show_subtitle "Prerequisites"
76+
7377
AC_CHECK_PROG([PERL],[perl],[perl],[no])
7478
AS_IF([test "X$PERL" = "Xno"],
7579
[AC_MSG_ERROR(["Open MPI requires perl. Aborting"])])
7680

77-
OPAL_CONFIGURE_SETUP
78-
opal_show_title "Configuring project_name_long"
79-
8081
#
8182
# Setup some things that must be done before AM-INIT-AUTOMAKE
8283
#
@@ -976,11 +977,17 @@ if test -z "$LEX" || \
976977
AC_MSG_WARN([*** Could not find Flex on your system.])
977978
AC_MSG_WARN([*** Flex is required for developer builds of Open MPI.])
978979
AC_MSG_WARN([*** Other versions of Lex are not supported.])
979-
AC_MSG_WARN([*** YOU DO NOT NEED FLEX WHEN BUILDING DISTRIBUTION TARBALLS!])
980+
AC_MSG_WARN([*** NOTE: If you are building a tarball downloaded from www.open-mpi.org, you do not need Flex])
980981
AC_MSG_ERROR([Cannot continue])
981982
fi
982983
fi
983984

985+
#
986+
# Setup man page processing
987+
#
988+
989+
OPAL_SETUP_MAN_PAGES
990+
984991
#
985992
# File system case sensitivity
986993
#

0 commit comments

Comments
 (0)