shmemc++(1)

✨ shmemc++ ✨ — the Open SHMEM C++ wrapper compiler (yes bestie, that's the whole vibe)

okay so picture this: shmemc++(1) is a little wrapper compiler that lives in your Open MPI install and its entire job is to make your Open SHMEM life effortless. It doesn't compile anything itself, it just holds the flags for you. Iconic behavior, honestly. 💅

---

🎀 SYNTAX 🎀

shmemc++ [-showme|-showme:compile|-showme:link] ...

that's it. that's the whole grammar. she's simple, she's elegant, she ate. 🦋

---

🌸 OPTIONS 🌸

• --showme — this one comes in a bunch of different variants (scroll down, they're all here). Here's the tea: none of the variants actually invokes the underlying compiler. They just spill the info on how that compiler would have been invoked if you hadn't used --showme. The plain --showme prints out the exact command line that would've been run to compile your program. 💖 NOTE: if you pass a non-filename argument on the command line, -showme won't show you any of the extra flags. Like, both shmemc++ --showme and shmemc++ --showme my_source.c will show you all the wrapper-supplied flags. But shmemc++ --showme -v will only show you the underlying compiler name and -v. that's it, no extras, periodt.
• --showme:compile — spits out the compiler flags that would have been handed to the C++ compiler. ✨
• --showme:link — spits out the linker flags that would have been handed to the C++ compiler. 🔗
• --showme:command — prints the underlying C++ compiler command (which could be one token or a whole little squad of tokens). 👑
• --showme:incdirs — prints a space-delimited (but otherwise completely undecorated, no frills) list of directories that the wrapper compiler would have given to the underlying C++ compiler, so it knows where the relevant header files live. 📁
• --showme:libdirs — prints a space-delimited (again, otherwise undecorated) list of directories the wrapper compiler would have given the underlying linker, so it knows where the relevant libraries live. 📚
• --showme:libs — prints a space-delimited (undecorated, you know the drill) list of library names the wrapper compiler would've used to link an application. for example: mpi open-rte open-pal util. 🔥
• --showme:version — prints the version number of Open MPI. 🏷️
• --showme:help — prints a lil brief usage help message. 🫶

and psst — go read the man page for your underlying C++ compiler for all the other options that can be passed straight through shmemc++. iykyk. 😌

---

💜 DESCRIPTION 💜

Conceptually? The role of these commands is genuinely so simple it's almost funny: they transparently add the relevant compiler and linker flags to your command line — the ones you need to compile / link Open SHMEM programs — and then they invoke the underlying compiler to actually do the thing.

So yeah, that's why everyone calls them "wrapper" compilers. They don't compile or link applications themselves. They just add command line flags and hand it off to the back-end compiler. middle-management energy but in a good way. 🧚

🦋 Background 🦋

Open MPI is made of three software layers: OPAL (Open Portable Access Layer), ORTE (Open Run-Time Environment), and OMPI (Open MPI). Every layer has its own wrapper compilers, and each layer's wrapper only links in the libraries that matter for that layer. Specifically, here's who ships what:

• OPAL
  • opalcc and opalc++
• ORTE
  • ortecc and ortec++
• OMPI
  • mpicc, mpic++, mpicxx, mpiCC (only on systems with case-senstive file systems), and mpifort (plus its legacy/deprecated names mpif77 and mpif90). Quick note bestie: mpic++, mpicxx, and mpiCC all invoke the same underlying C++ compiler with the same options. They all exist purely for compatibility with other MPI implementations. 💅

🌈 Fortran Notes 🌈

The Fortran wrapper compiler for MPI (mpifort, plus its legacy/deprecated names mpif77 and mpif90) can compile and link MPI applications that use any/all of the MPI Fortran bindings: mpif.h, the mpi module, and the mpi_f08 module — assuming Open MPI was installed with support for each of those Fortran bindings. Specifically: you no longer need different wrapper compilers for apps using mpif.h vs. apps using the mpi module. Just use mpifort for all your Fortran MPI applications. one wrapper to rule them all. 👑

But heads up — the Fortran compiler may need extra command-line options to enforce a specific Fortran dialect. For example, in some versions of the IBM XLF compiler, if xlf90 is the underlying Fortran compiler, -qfixed may be necessary to compile fixed-format Fortran source files. 📝

And finally: mpifort will be inoperative and will return an error on use if Fortran support was not built into the MPI layer. so don't be surprised, ok? 😭

⭐ Overview ⭐

shmemc++ is a convenience wrapper for the underlying C++ compiler. Translating an Open SHMEM program requires linking the Open SHMEM-specific libraries, which may not live in one of the standard search directories of ld(1). It also often requires including header files that may also not be found in a standard location.

shmemc++ passes its arguments to the underlying C++ compiler along with the -I, -L and -l options that Open SHMEM programs require.

The Open SHMEM Team strongly encourages you to use the wrapper compilers instead of trying to link to the Open SHMEM libraries manually. Why? Because this lets the specific implementation of Open SHMEM change without forcing you to change linker directives in your Makefiles. And fr fr — the specific set of flags and libraries the wrapper compilers use depends on how Open SHMEM was configured and built. Those values can change between different installations of the same version of Open SHMEM. 🙈

And honestly, since the wrappers are just thin shells on top of an underlying compiler, there are very, very few compelling reasons not to use shmemc++. When it's not possible to use the wrappers directly, use the -showme:compile and -showme:link options to figure out what flags the wrappers would have used. For example:

shell$ cc -c file1.c `mpicc -showme:compile`

shell$ cc -c file2.c `mpicc -showme:compile`

shell$ cc file1.o file2.o `mpicc -showme:link` -o my_mpi_program

---

🫶 NOTES 🫶

It is possible to make the wrapper compilers multi-lib aware. That is, the libraries and includes specified may differ based on the compiler flags you specify. (For example, with the GNU compilers on Linux, a different library path may be used if -m32 is seen versus -m64 being seen.) This is not the default behavior in a standard build, but it can be activated — for example, in a binary package providing both 32 and 64 bit support. More info can be found at:

https://github.com/open-mpi/ompi/wiki/compilerwrapper3264

---

🍓 FILES 🍓

The string that the wrapper compilers insert into the command line before invoking the underlying compiler is stored in a text file created by Open SHMEM and installed to $pkgdata/shmemc++-wrapper-data.txt, where $pkgdata is typically $prefix/share/openmpi, and $prefix is the top installation directory of Open SHMEM.

It is rarely necessary to edit this file, but you can examine it to gain insight into what flags the wrappers are placing on the command line. peek at it, it's your data, bestie. 👀

---

🧚 ENVIRONMENT VARIABLES 🧚

By default, the wrappers use the compilers that were selected when Open SHMEM was configured. These compilers were either found automatically by Open MPI's "configure" script, or selected by the user in the CC, CXX, F77, and/or FC environment variables before "configure" was invoked. Additionally, other arguments specific to the compiler may have been selected by configure.

These values can be selectively overridden — either by editing the text files containing this configuration info (see the FILES section above 👆), or by setting selected environment variables of the form "OSHMEM_value".

Valid value names are:

• CPPFLAGS — flags added when invoking the preprocessor (C or C++) ✨
• LDFLAGS — flags added when invoking the linker (C, C++, or Fortran) 🔗
• LIBS — libraries added when invoking the linker (C, C++, or Fortran) 📚
• CC — C compiler
• CFLAGS — C compiler flags
• CXX — C++ compiler
• CXXFLAGS — C++ compiler flags
• FC — Fortran compiler
• FCFLAGS — Fortran compiler flags

---

and that's the whole page, bestie!! 💖 this was version 4.1.6, dated Sep 30, 2023, brought to you by the Open MPI girlies. go compile something cute. mwah. 🎀✨💅