lstopo: Add output option for LaTeX tikzpicture

Clement Foyer · bgoglin · commit 2ccb19dd565d · 2020-07-23T16:57:50.000+02:00
This output option generates a standalone picture to be compiled with
pdflatex.  The colors are defined using the xcolor package.  If only the
tikzpicture is of interest, one can extract the image code by copying
the lines between
"%%%%% If inserting in another document, this is the actual source code of the picture %%%%%"
and
"%%%%% End of actual source code of the picture to insert in another document %%%%%",
however, some lines also have to be copied to the document preambule.

Signed-off-by: Clement Foyer &lt;cfoyer@hpe.com&gt;
diff --git a/NEWS b/NEWS
@@ -2,6 +2,7 @@ Copyright © 2009 CNRS
 Copyright © 2009-2020 Inria.  All rights reserved.
 Copyright © 2009-2013 Université Bordeaux
 Copyright © 2009-2011 Cisco Systems, Inc.  All rights reserved.
+Copyright © 2020 Hewlett-Packard Enterprise.  All rights reserved.
 
 $COPYRIGHT$
 
@@ -29,6 +30,8 @@ Version 2.3.0
   + Tools that have a --restrict option may now receive a nodeset or
     some custom flags for restricting the topology.
   + Fix lstopo drawing when autoresizing on Windows 10
+  + Add a tikz lstopo graphical backend to generate picture easily included into
+    LaTeX documents.
 
 
 Version 2.2.0
diff --git a/contrib/windows/lstopo-no-graphics.vcxproj b/contrib/windows/lstopo-no-graphics.vcxproj
@@ -72,6 +72,7 @@
     <ClCompile Include="..\..\utils\lstopo\lstopo.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-ascii.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-draw.c" />
+    <ClCompile Include="..\..\utils\lstopo\lstopo-tikz.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-fig.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-svg.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-text.c" />
diff --git a/contrib/windows/lstopo-no-graphics.vcxproj.filters b/contrib/windows/lstopo-no-graphics.vcxproj.filters
@@ -24,6 +24,9 @@
     <ClCompile Include="..\..\utils\lstopo\lstopo-draw.c">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="..\..\utils\lstopo\lstopo-tikz.c">
+      <Filter>Source Files</Filter>
+    </ClCompile>
     <ClCompile Include="..\..\utils\lstopo\lstopo-fig.c">
       <Filter>Source Files</Filter>
     </ClCompile>
diff --git a/contrib/windows/lstopo-win.vcxproj b/contrib/windows/lstopo-win.vcxproj
@@ -73,6 +73,7 @@
     <ClCompile Include="..\..\utils\lstopo\lstopo.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-ascii.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-draw.c" />
+    <ClCompile Include="..\..\utils\lstopo\lstopo-tikz.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-fig.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-svg.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-text.c" />
diff --git a/contrib/windows/lstopo-win.vcxproj.filters b/contrib/windows/lstopo-win.vcxproj.filters
@@ -24,6 +24,9 @@
     <ClCompile Include="..\..\utils\lstopo\lstopo-draw.c">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="..\..\utils\lstopo\lstopo-tikz.c">
+      <Filter>Source Files</Filter>
+    </ClCompile>
     <ClCompile Include="..\..\utils\lstopo\lstopo-fig.c">
       <Filter>Source Files</Filter>
     </ClCompile>
diff --git a/contrib/windows/lstopo.vcxproj b/contrib/windows/lstopo.vcxproj
@@ -72,6 +72,7 @@
     <ClCompile Include="..\..\utils\lstopo\lstopo.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-ascii.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-draw.c" />
+    <ClCompile Include="..\..\utils\lstopo\lstopo-tikz.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-fig.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-svg.c" />
     <ClCompile Include="..\..\utils\lstopo\lstopo-text.c" />
diff --git a/contrib/windows/lstopo.vcxproj.filters b/contrib/windows/lstopo.vcxproj.filters
@@ -24,6 +24,9 @@
     <ClCompile Include="..\..\utils\lstopo\lstopo-draw.c">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="..\..\utils\lstopo\lstopo-tikz.c">
+      <Filter>Source Files</Filter>
+    </ClCompile>
     <ClCompile Include="..\..\utils\lstopo\lstopo-fig.c">
       <Filter>Source Files</Filter>
     </ClCompile>
diff --git a/doc/hwloc.doxy b/doc/hwloc.doxy
@@ -3,6 +3,7 @@
  * Copyright © 2009-2020 Inria.  All rights reserved.
  * Copyright © 2009-2013 Université Bordeaux
  * Copyright © 2009-2020 Cisco Systems, Inc.  All rights reserved.
+ * Copyright © 2020 Hewlett-Packard Enterprise.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -84,7 +85,7 @@ work on "fake" topologies:
 
 hwloc can display the topology in a human-readable format, either in
 graphical mode (X11), or by exporting in one of several different
-formats, including: plain text, PDF, PNG, and FIG (see \ref cli_examples
+formats, including: plain text, LaTeX tikzpicture, PDF, PNG, and FIG (see \ref cli_examples
 below).  Note that some of the export formats require additional
 support libraries.
 
diff --git a/utils/lstopo/Makefile.am b/utils/lstopo/Makefile.am
@@ -1,6 +1,7 @@
 # Copyright © 2009-2019 Inria.  All rights reserved.
 # Copyright © 2009-2012, 2014 Université Bordeaux
 # Copyright © 2009-2014 Cisco Systems, Inc.  All rights reserved.
+# Copyright © 2020 Hewlett-Packard Enterprise.  All rights reserved.
 #
 # See COPYING in top-level directory.
 
@@ -24,6 +25,7 @@ lstopo_no_graphics_SOURCES = \
         lstopo.h \
         lstopo.c \
         lstopo-draw.c \
+        lstopo-tikz.c \
         lstopo-fig.c \
         lstopo-svg.c \
         lstopo-ascii.c \
diff --git a/utils/lstopo/lstopo-no-graphics.1in b/utils/lstopo/lstopo-no-graphics.1in
@@ -2,6 +2,7 @@
 .\" Copyright © 2009-2020 Inria.  All rights reserved.
 .\" Copyright © 2009-2010 Université of Bordeaux
 .\" Copyright © 2009-2010 Cisco Systems, Inc.  All rights reserved.
+.\" Copyright © 2020 Hewlett-Packard Enterprise.  All rights reserved.
 .\" See COPYING in top-level directory.
 .TH LSTOPO "1" "%HWLOC_DATE%" "%PACKAGE_VERSION%" "%PACKAGE_NAME%"
 .SH NAME
@@ -447,6 +448,11 @@ If outputting to stdout and if colors are supported on the terminal,
 the output will be colorized.
 .
 .TP
+.B tikz or tex
+Output a LaTeX tikzpicture representation of the map that can be
+compiled with a LaTeX compiler.
+.
+.TP
 .B fig
 Output a representation of the map that can be loaded in Xfig.
 .
diff --git a/utils/lstopo/lstopo-tikz.c b/utils/lstopo/lstopo-tikz.c
@@ -0,0 +1,168 @@
+/*
+ * Copyright © 2020 Hewlett-Packard Enterprise.  All rights reserved.
+ * See COPYING in top-level directory.
+ */
+
+#include "private/autogen/config.h"
+#include "hwloc.h"
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+#include <errno.h>
+
+#include "lstopo.h"
+
+#define TIKZ_TEXT_WIDTH(length, fontsize) (((length) * (fontsize))/2.2)
+#define TIKZ_FONTSIZE_SCALE(size) (((size) * 11) / 9)
+
+#define TIKZ_FONTFAMILY_ENV "LSTOPO_TIKZ_FONTFAMILY"
+
+static const char *
+tikz_get_font_family(void)
+{
+  /* Authorized values (case insensitive): sf, rm, tt */
+  char *font_request = getenv(TIKZ_FONTFAMILY_ENV);
+  if (!font_request || !(*font_request))
+    return ""; /* use latex default font family */
+  else if (!strcasecmp(font_request, "sf"))
+    return "\\sffamily";
+  else if (!strcasecmp(font_request, "rm"))
+    return "\\rmfamily";
+  else if (!strcasecmp(font_request, "tt"))
+    return "\\ttfamily";
+  else
+    return NULL;
+}
+
+static int
+tikz_declare_color(struct lstopo_output *loutput, struct lstopo_color *lcolor)
+{
+  int r = lcolor->r, g = lcolor->g, b = lcolor->b;
+  FILE *file = loutput->backend_data;
+
+  /* TODO: add random seed in name to avoid collisions
+   * name format proposed: hwloc-color-<seed>-<r>-<g>-<b>
+   */
+  fprintf(file, "\\definecolor{hwloc-color-%d-%d-%d}{RGB}{%d,%d,%d}\n",
+          r, g, b, r, g, b);
+  return 0;
+}
+
+static void
+tikz_box(struct lstopo_output *loutput, const struct lstopo_color *lcolor, unsigned depth __hwloc_attribute_unused, unsigned x, unsigned width, unsigned y, unsigned height, hwloc_obj_t obj __hwloc_attribute_unused, unsigned box_id __hwloc_attribute_unused)
+{
+  FILE *file = loutput->file;
+  int r = lcolor->r, g = lcolor->g, b = lcolor->b;
+
+  fprintf(file, "\t\\filldraw [fill=hwloc-color-%d-%d-%d,draw=black,line width=1pt] (%u,%u) rectangle ++(%u,%u);\n",
+          r, g, b, x, y, width, height);
+}
+
+
+static void
+tikz_line(struct lstopo_output *loutput, const struct lstopo_color *lcolor, unsigned depth __hwloc_attribute_unused, unsigned x1, unsigned y1, unsigned x2, unsigned y2, hwloc_obj_t obj __hwloc_attribute_unused, unsigned line_id __hwloc_attribute_unused)
+{
+  FILE *file = loutput->file;
+  int r = lcolor->r, g = lcolor->g, b = lcolor->b;
+
+  fprintf(file, "\t\\draw [draw=hwloc-color-%d-%d-%d,line width=1pt] (%u,%u) -- (%u,%u);\n",
+          r, g, b, x1, y1, x2, y2);
+}
+
+static void
+tikz_textsize(struct lstopo_output *loutput __hwloc_attribute_unused, const char *text __hwloc_attribute_unused, unsigned textlength, unsigned fontsize, unsigned *width)
+{
+  fontsize = TIKZ_FONTSIZE_SCALE(fontsize);
+  *width = TIKZ_TEXT_WIDTH(textlength, fontsize);
+}
+
+
+static void
+tikz_text(struct lstopo_output *loutput, const struct lstopo_color *lcolor, int size __hwloc_attribute_unused, unsigned depth __hwloc_attribute_unused, unsigned x, unsigned y, const char *text, hwloc_obj_t obj __hwloc_attribute_unused, unsigned text_id __hwloc_attribute_unused)
+{
+  FILE *file = loutput->file;
+  int r = lcolor->r, g = lcolor->g, b = lcolor->b;
+
+  const char *tikzdelim = "{}%&#";
+
+  fprintf(file, "\t\\node [hwloc-label,text=hwloc-color-%d-%d-%d] at (%u,%u) {",
+          r, g, b, x, y);
+  while (*text) {
+    size_t chunksize = strcspn(text, tikzdelim), n_delim;
+    fprintf(file, "%.*s", (int) chunksize, text);
+    text += chunksize;
+    for (n_delim = strspn(text, tikzdelim); *text && n_delim; ++text, --n_delim)
+      fprintf(file, "\\%c", *text);
+  }
+  fprintf(file, "};\n");
+}
+
+static struct draw_methods tikz_draw_methods = {
+  tikz_declare_color,
+  tikz_box,
+  tikz_line,
+  tikz_text,
+  tikz_textsize,
+};
+
+int output_tikz(struct lstopo_output * loutput, const char *filename)
+{
+  const char *font_family;
+  FILE *output = open_output(filename, loutput->overwrite);
+  if (!output) {
+    fprintf(stderr, "Failed to open %s for writing (%s)\n", filename, strerror(errno));
+    return -1;
+  }
+
+  font_family = tikz_get_font_family();
+  if (!font_family) {
+    fprintf(stderr, "Invalid value for %s. The only accepted values are \"rm\", \"sf\" and \"tt\".\n",
+            TIKZ_FONTFAMILY_ENV);
+    if (output != stdout)
+      fclose(output);
+    return -1;
+  }
+
+  loutput->file = output;
+  loutput->methods = &tikz_draw_methods;
+  loutput->backend_data = output;
+
+  /* recurse once for preparing sizes and positions */
+  loutput->drawing = LSTOPO_DRAWING_PREPARE;
+  output_draw(loutput);
+  loutput->drawing = LSTOPO_DRAWING_DRAW;
+
+  /* ready */
+
+  /* Write LaTeX header */
+  fprintf(output, "\\documentclass{standalone}\n");
+
+  /* Write required LaTeX preambule */
+  fprintf(output, "\n%%%%%%%%%% If inserting in another document, the following lines below must be copied before \\begin{document} %%%%%%%%%%\n\n");
+  fprintf(output, "\\usepackage{tikz}\n\\usepackage{xcolor}\n");
+  declare_colors(loutput);
+  lstopo_prepare_custom_styles(loutput); /* Add custom colors to the preambule */
+  fprintf(output, "\n%%%%%%%%%% End of lines needed before \\begin{document}  %%%%%%%%%%\n\n");
+
+  fprintf(output, "\\begin{document}\n");
+
+  /* Write actual image code */
+  fprintf(output, "\n%%%%%%%%%% If inserting in another document, this is the actual source code of the picture %%%%%%%%%%\n\n");
+  fprintf(output, "\\begin{tikzpicture}[x=1pt,y=1pt,yscale=-1,"
+                  "hwloc-label/.style={fill=none,draw=none,text=black,align=left,anchor=north west,"
+                  "outer sep=0pt,inner sep=0pt,font=\\fontsize{%d}{%d}\\selectfont%s}]\n",
+                  loutput->fontsize, loutput->fontsize + loutput->linespacing, font_family);
+  fprintf(output, "\t\\clip (0,0) rectangle (%u,%u);\n", loutput->width, loutput->height);
+  output_draw(loutput);
+  fprintf(output,"\\end{tikzpicture}\n");
+  fprintf(output, "\n%%%%%%%%%% End of actual source code of the picture to insert in another document %%%%%%%%%%\n\n");
+
+  /* Write LaTeX footer */
+  fprintf(output, "\\end{document}\n");
+
+  if (output != stdout)
+    fclose(output);
+
+  return 0;
+}
diff --git a/utils/lstopo/lstopo.c b/utils/lstopo/lstopo.c
@@ -3,6 +3,7 @@
  * Copyright © 2009-2020 Inria.  All rights reserved.
  * Copyright © 2009-2012, 2015, 2017 Université Bordeaux
  * Copyright © 2009-2011 Cisco Systems, Inc.  All rights reserved.
+ * Copyright © 2020 Hewlett-Packard Enterprise.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -337,7 +338,7 @@ void usage(const char *name, FILE *where)
 #endif
 		  ".\n");
 
-  fprintf (where, "Supported output file formats: console, ascii, fig"
+  fprintf (where, "Supported output file formats: console, ascii, tikz, fig"
 #ifdef LSTOPO_HAVE_GRAPHICS
 #ifdef CAIRO_HAS_PDF_SURFACE
 		  ", pdf"
@@ -512,6 +513,7 @@ enum output_format {
   LSTOPO_OUTPUT_CONSOLE,
   LSTOPO_OUTPUT_SYNTHETIC,
   LSTOPO_OUTPUT_ASCII,
+  LSTOPO_OUTPUT_TIKZ,
   LSTOPO_OUTPUT_FIG,
   LSTOPO_OUTPUT_PNG,
   LSTOPO_OUTPUT_PDF,
@@ -536,6 +538,8 @@ parse_output_format(const char *name, char *callname __hwloc_attribute_unused)
   else if (!strcasecmp(name, "ascii")
 	   || !strcasecmp(name, "txt") /* backward compat with 1.10 */)
     return LSTOPO_OUTPUT_ASCII;
+  else if (!strcasecmp(name, "tikz") || !strcasecmp(name, "tex"))
+    return LSTOPO_OUTPUT_TIKZ;
   else if (!strcasecmp(name, "fig"))
     return LSTOPO_OUTPUT_FIG;
   else if (!strcasecmp(name, "png"))
@@ -1337,6 +1341,9 @@ main (int argc, char *argv[])
   case LSTOPO_OUTPUT_ASCII:
     output_func = output_ascii;
     break;
+  case LSTOPO_OUTPUT_TIKZ:
+    output_func = output_tikz;
+    break;
   case LSTOPO_OUTPUT_FIG:
     output_func = output_fig;
     break;
diff --git a/utils/lstopo/lstopo.h b/utils/lstopo/lstopo.h
@@ -3,6 +3,7 @@
  * Copyright © 2009-2019 Inria.  All rights reserved.
  * Copyright © 2009-2010, 2012, 2015 Université Bordeaux
  * Copyright © 2011 Cisco Systems, Inc.  All rights reserved.
+ * Copyright © 2020 Hewlett-Packard Enterprise.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -192,7 +193,7 @@ struct lstopo_obj_userdata {
 };
 
 typedef int output_method (struct lstopo_output *output, const char *filename);
-extern output_method output_console, output_synthetic, output_ascii, output_fig, output_png, output_pdf, output_ps, output_nativesvg, output_cairosvg, output_x11, output_windows, output_xml, output_shmem;
+extern output_method output_console, output_synthetic, output_ascii, output_tikz, output_fig, output_png, output_pdf, output_ps, output_nativesvg, output_cairosvg, output_x11, output_windows, output_xml, output_shmem;
 
 extern int lstopo_shmem_adopt(const char *input, hwloc_topology_t *topologyp);
 
diff --git a/utils/lstopo/test-lstopo.sh.in b/utils/lstopo/test-lstopo.sh.in
@@ -5,6 +5,7 @@
 # Copyright © 2009 CNRS
 # Copyright © 2009-2020 Inria.  All rights reserved.
 # Copyright © 2009, 2011 Université Bordeaux
+# Copyright © 2020 Hewlett-Packard Enterprise.  All rights reserved.
 # See COPYING in top-level directory.
 #
 
@@ -75,6 +76,16 @@ $ls --top > $tmp/test.top
 
 echo "** ASCII output in $tmp/test.ascii ..."
 $ls $tmp/test.ascii
+
+echo "** LaTeX Tikzpicture output in $tmp/test.tikz ..."
+$ls $tmp/test.tikz
+echo "** LaTeX Tikzpicture output in $tmp/test.tex ..."
+$ls $tmp/test.tex
+if [ -n "$PDFLATEX" ]; then
+  echo "** Test validity of the generated LaTeX output from $tmp/test.tikz ..."
+  (cd $tmp && $PDFLATEX test.tikz && $PDFLATEX test.tex)
+fi
+
 echo "** FIG output in $tmp/test.fig ..."
 $ls $tmp/test.fig
 echo "** Native SVG output in $tmp/test.nativesvg ..."
