/*!

\mainpage Hardware Locality

Portable abstraction of parallel architectures for high-performance computing

\htmlonly

\endhtmlonly

\section common_introduction Introduction

The Hardware Locality (hwloc) software project aims at easing the process

of discovering hardware resources in parallel architectures.

It offers command-line tools and a C API for consulting these

resources, their locality, attributes, and interconnection.

hwloc primarily aims at helping high-performance computing (HPC)

applications, but is also applicable to any project seeking to exploit

code and/or data locality on modern computing platforms.

hwloc is actually made of two subprojects distributed together:

The original hwloc project for describing the internals of computing nodes.

It is described in details starting at section \ref hwloc_intro.

The network-oriented companion called netloc (Network Locality),

described in details starting with section \ref netloc_intro.

\htmlonly

See also the Related pages tab above for links to other sections.

\endhtmlonly

Netloc may be disabled, but the original hwloc cannot.

Both hwloc and netloc APIs are documented after these sections.

\htmlonly

\endhtmlonly

\section common_installation Installation

hwloc (http://www.open-mpi.org/projects/hwloc/) is available under the

BSD license.  It is hosted as a sub-project of the overall Open MPI

project (http://www.open-mpi.org/).  Note that hwloc does not require

any functionality from Open MPI -- it is a wholly separate (and much

smaller!) project and code base.  It just happens to be hosted as part

of the overall Open MPI project.

\subsection basic_installation Basic Installation

Installation is the fairly common GNU-based process:

\verbatim

shell$ ./configure --prefix=...

shell$ make

shell$ make install

\endverbatim

hwloc- and netloc-specific configure options and requirements are

documented in sections \ref hwloc_installation and \ref netloc_installation

respectively.

Also note that if you install supplemental libraries in non-standard

locations, hwloc's configure script may not be able to find them

without some help.  You may need to specify additional CPPFLAGS,

LDFLAGS, or PKG_CONFIG_PATH values on the configure command line.

For example, if libpciaccess was installed into /opt/pciaccess,

hwloc's configure script may not find it be default.  Try adding

PKG_CONFIG_PATH to the ./configure command line, like this:

\verbatim

./configure PKG_CONFIG_PATH=/opt/pciaccess/lib/pkgconfig ...

\endverbatim

Running the "lstopo" tool is a good way to check as a graphical output

whether hwloc properly detected the architecture of your node.

Netloc command-line tools can be used to display the network topology

interconnecting your nodes.

\subsection gitclone_installation Installing from a Git clone

Additionally, the code can be directly cloned from Git:

\verbatim

shell$ git clone https://github.com/open-mpi/hwloc.git

shell$ cd hwloc

shell$ ./autogen.sh

\endverbatim

Note that GNU Autoconf >=2.63, Automake >=1.11 and Libtool >=2.2.6 are

required when building from a Git clone.

Nightly development snapshots are available on the web site,

they can be configured and built without any need for Git

or GNU Autotools.

\htmlonly

\endhtmlonly

\section bugs Questions and Bugs

Bugs should be reported in the tracker

(https://github.com/open-mpi/hwloc/issues).

Opening a new issue automatically displays lots of hints about

how to debug and report issues.

Questions may be sent to the users or developers mailing lists

(http://www.open-mpi.org/community/lists/hwloc.php).

There is also a <tt>\#hwloc</tt> IRC channel on Freenode (<tt>irc.freenode.net</tt>).

*/

\input hwloc.doxy

\input netloc.doxy