From 7c900fc43ade496bbea9c5789274750d9f4fd25f Mon Sep 17 00:00:00 2001 From: Elliott Slaughter Date: Tue, 4 Oct 2022 14:21:26 -0700 Subject: [PATCH] Update instructions for CMake build. --- coherence.tex | 7 ++-- control_replication.tex | 4 +-- docker/Dockerfile.latex | 2 +- installation.tex | 44 +++++++++++++++++++------ legion.tex | 72 +++++++++++++++++++++++++++++++++++++++++ mapping.tex | 7 ++-- partitioning.tex | 24 ++++---------- regions.tex | 16 ++++----- tasks.tex | 71 ++++++++++++++-------------------------- 9 files changed, 148 insertions(+), 99 deletions(-) diff --git a/coherence.tex b/coherence.tex index d1d4d67..7f8e159 100644 --- a/coherence.tex +++ b/coherence.tex @@ -16,9 +16,7 @@ \section{Atomic} \label{sec:atomic} \begin{figure} - {\small - \lstinputlisting[linerange={16-58}]{Examples/Coherence/atomic/atomic.cc} - } + \lstinputlisting[language=C++,linerange={16-58}]{Examples/Coherence/atomic/atomic.cc} \caption{\legionbook{Coherence/atomic/atomic.cc}} \label{fig:atomic} \end{figure} @@ -148,8 +146,7 @@ \section{Simultaneous} \end{itemize} \begin{figure} - \centering - \lstinputlisting[linerange={16-77}]{Examples/Coherence/simultaneous/sim.cc} + \lstinputlisting[language=C++,linerange={16-77}]{Examples/Coherence/simultaneous/sim.cc} \caption{\legionbook{Coherene/simultaneous/sim.cc}} \label{fig:sim} \end{figure} diff --git a/control_replication.tex b/control_replication.tex index 34288ec..282065e 100644 --- a/control_replication.tex +++ b/control_replication.tex @@ -3,9 +3,7 @@ \chapter{Control Replication} \begin{figure} - {\small - \lstinputlisting[linerange={15-44,59-74}]{Examples/ControlReplication/sum/cp.cc} - } + \lstinputlisting[language=C++,linerange={15-44,59-74}]{Examples/ControlReplication/sum/cp.cc} \caption{\legionbook{ControlReplication/sum/cp.cc}} \label{fig:ctrlrep} \end{figure} diff --git a/docker/Dockerfile.latex b/docker/Dockerfile.latex index c10a008..bcc8412 100644 --- a/docker/Dockerfile.latex +++ b/docker/Dockerfile.latex @@ -9,7 +9,7 @@ ENV DEBIAN_FRONTEND noninteractive COPY . /build RUN apt-get update -qq && \ - apt-get install -qq git make texlive && \ + apt-get install -qq git make texlive texlive-fonts-extra && \ apt-get clean RUN cd /build && make diff --git a/installation.tex b/installation.tex index 54f016e..d2381e3 100644 --- a/installation.tex +++ b/installation.tex @@ -3,18 +3,42 @@ \chapter{Installation} The Legion homepage is \url{https://legion.stanford.edu}. Here you will find links to everything associated with the project, including a set of -tutorials that are distinct from this manual. The Legion distribution is at +tutorials that are distinct from this manual. The Legion software distribution is at \url{https://github.com/StanfordLegion/legion}. The distribution has been -tested on Linux and macOS. To install, in a shell type -\begin{lstlisting} -> cd DIR -> git clone https://github.com/StanfordLegion/legion +tested on Linux and macOS. + +To install Legion, open a shell and type: + +\begin{lstlisting}[language=bash,style=inline] +git clone https://github.com/StanfordLegion/legion.git +cd legion +mkdir build install +cd build +cmake .. -DCMAKE_INSTALL_PREFIX=$PWD/../install +make install -j4 +cd ../.. \end{lstlisting} -where {\tt DIR} is a directory of your choice. This command creates -the directory {\tt DIR/legion}. To complete the installation, -set the environment variable {\tt LG\_RT\_DIR} to {\tt DIR/legion/runtime}. -For {\tt bash} users, an example {\tt .bashrc} is included in -\legionbook{Installation}. + +This installs Legion into the directory +\lstinline{legion/install}. Note that by default, a debug build is +created. To build a release copy of Legion, add +\lstinline{-DCMAKE_BUILD_Type=Release} the the \lstinline{cmake} +command. (A debug build is strongly recommended when initially +developing with Legion, as it enables a number of checks for correct +usage of Legion APIs, in addition to enabling debug symbols.) + +The examples in this manual can then be downloaded and built with: + +\begin{lstlisting}[language=bash,style=inline] +git clone https://github.com/StanfordLegion/legion-manual.git +cd legion-manual +mkdir build +cmake ../Examples -DCMAKE_PREFIX_PATH=$PWD/../../legion/install +make -j4 +\end{lstlisting} + +All of the examples in this manual are included in the build, and will +be located under the \lstinline{legion-manual/build} directory. \section{Regent} diff --git a/legion.tex b/legion.tex index 4663fa2..7709825 100644 --- a/legion.tex +++ b/legion.tex @@ -7,12 +7,84 @@ \usepackage{url} \usepackage{graphicx} \usepackage{microtype} +\usepackage{xcolor} +\usepackage{geometry} % widen the page margins a bit + +\usepackage{inconsolata} % the default monospace font is ugly \lstset{upquote=true} \newcommand{\legionbook}[1]{{\tt Examples/#1}} \newcommand{\Cpp}{C++} +% use Eisvogen style for code highlighting +% https://github.com/Wandmalfarbe/pandoc-latex-template/blob/04e329698d01c3a25aa72ad81d98483284669316/eisvogel.tex + +% +% general listing colors +% +\definecolor{listing-background}{HTML}{F7F7F7} +\definecolor{listing-rule}{HTML}{B3B2B3} +\definecolor{listing-numbers}{HTML}{B3B2B3} +\definecolor{listing-text-color}{HTML}{000000} +\definecolor{listing-keyword}{HTML}{435489} +\definecolor{listing-keyword-2}{HTML}{1284CA} % additional keywords +\definecolor{listing-keyword-3}{HTML}{9137CB} % additional keywords +\definecolor{listing-identifier}{HTML}{435489} +\definecolor{listing-string}{HTML}{00999A} +\definecolor{listing-comment}{HTML}{8E8E8E} + +\lstdefinestyle{eisvogel_listing_style}{ + numbers = left, + xleftmargin = 2.7em, + framexleftmargin = 2.5em, + backgroundcolor = \color{listing-background}, + basicstyle = \color{listing-text-color}\linespread{1.0}% + \lst@ifdisplaystyle% + \scriptsize% + \fi\ttfamily{}, + breaklines = true, + frame = single, + framesep = 0.19em, + rulecolor = \color{listing-rule}, + frameround = ffff, + tabsize = 4, + numberstyle = \color{listing-numbers}, + aboveskip = 1.0em, + belowskip = 0.1em, + abovecaptionskip = 0em, + belowcaptionskip = 1.0em, + keywordstyle = {\color{listing-keyword}\bfseries}, + keywordstyle = {[2]\color{listing-keyword-2}\bfseries}, + keywordstyle = {[3]\color{listing-keyword-3}\bfseries\itshape}, + sensitive = true, + identifierstyle = \color{listing-identifier}, + commentstyle = \color{listing-comment}, + stringstyle = \color{listing-string}, + showstringspaces = false, + escapeinside = {/*@}{@*/}, % Allow LaTeX inside these special comments + literate = + {á}{{\'a}}1 {é}{{\'e}}1 {í}{{\'i}}1 {ó}{{\'o}}1 {ú}{{\'u}}1 + {Á}{{\'A}}1 {É}{{\'E}}1 {Í}{{\'I}}1 {Ó}{{\'O}}1 {Ú}{{\'U}}1 + {à}{{\`a}}1 {è}{{\'e}}1 {ì}{{\`i}}1 {ò}{{\`o}}1 {ù}{{\`u}}1 + {À}{{\`A}}1 {È}{{\'E}}1 {Ì}{{\`I}}1 {Ò}{{\`O}}1 {Ù}{{\`U}}1 + {ä}{{\"a}}1 {ë}{{\"e}}1 {ï}{{\"i}}1 {ö}{{\"o}}1 {ü}{{\"u}}1 + {Ä}{{\"A}}1 {Ë}{{\"E}}1 {Ï}{{\"I}}1 {Ö}{{\"O}}1 {Ü}{{\"U}}1 + {â}{{\^a}}1 {ê}{{\^e}}1 {î}{{\^i}}1 {ô}{{\^o}}1 {û}{{\^u}}1 + {Â}{{\^A}}1 {Ê}{{\^E}}1 {Î}{{\^I}}1 {Ô}{{\^O}}1 {Û}{{\^U}}1 + {œ}{{\oe}}1 {Œ}{{\OE}}1 {æ}{{\ae}}1 {Æ}{{\AE}}1 {ß}{{\ss}}1 + {ç}{{\c c}}1 {Ç}{{\c C}}1 {ø}{{\o}}1 {å}{{\r a}}1 {Å}{{\r A}}1 + {€}{{\EUR}}1 {£}{{\pounds}}1 {«}{{\guillemotleft}}1 + {»}{{\guillemotright}}1 {ñ}{{\~n}}1 {Ñ}{{\~N}}1 {¿}{{?`}}1 + {…}{{\ldots}}1 {≥}{{>=}}1 {≤}{{<=}}1 {„}{{\glqq}}1 {“}{{\grqq}}1 + {”}{{''}}1 +} +\lstset{style=eisvogel_listing_style} + +\lstdefinestyle{inline}{ + numbers=none, +} + \begin{document} \title{Programming with Legion} diff --git a/mapping.tex b/mapping.tex index 39cba67..6730125 100644 --- a/mapping.tex +++ b/mapping.tex @@ -86,9 +86,7 @@ \subsection{Mapper Registration} example registering a custom mapper. \begin{figure} -{ \small - \lstinputlisting[linerange={14,78}]{Examples/Mapping/registration/registration.cc} - } +\lstinputlisting[language=C++,linerange={14,78}]{Examples/Mapping/registration/registration.cc} \caption{\legionbook{Mapping/registration/registration.cc}} \label{fig:mapper_registration} \end{figure} @@ -227,8 +225,7 @@ \subsection{Machine Interface} commonly invoked queries to avoid duplicated work. \begin{figure} - {\small -\lstinputlisting[linerange={22,80}]{Examples/Mapping/machine/machine.cc}} +\lstinputlisting[language=C++,linerange={22,80}]{Examples/Mapping/machine/machine.cc} \caption{\legionbook{Mapping/machine/machine.cc}} \label{fig:mapper_machine} \end{figure} diff --git a/partitioning.tex b/partitioning.tex index 1008165..5499e76 100644 --- a/partitioning.tex +++ b/partitioning.tex @@ -100,9 +100,7 @@ \section{Equal Partitions} \begin{figure} - {\small - \lstinputlisting[linerange={15-49}]{Examples/Partitions/equal/equal.cc} - } + \lstinputlisting[language=C++,linerange={15-49}]{Examples/Partitions/equal/equal.cc} \caption{\legionbook{Partitions/equal/equal.cc}} \label{fig:equalpart} \end{figure} @@ -130,9 +128,7 @@ \section{Partition by Field} The logic for launching the {\tt sum\_task} over the paritition on lines 31-35 is the same as in Figure~\ref{fig:equalpart}. \begin{figure} - {\small - \lstinputlisting[linerange={17-74}]{"Examples/Partitions/partition_by_field/pbf.cc"} - } + \lstinputlisting[language=C++,linerange={17-74}]{"Examples/Partitions/partition_by_field/pbf.cc"} \caption{\legionbook{Partitions/partition\_by\_field/pbf.cc}} \label{fig:pbf} \end{figure} @@ -168,9 +164,7 @@ \section{Partition by Restriction} of the subregion---for a region with an index space 0..99, it is necessary that the color space be $0..3$ and not some other set of four points. \begin{figure} - {\small - \lstinputlisting[linerange={15-49}]{"Examples/Partitions/partition_by_restriction/pbr.cc"} - } + \lstinputlisting[language=C++,linerange={15-49}]{"Examples/Partitions/partition_by_restriction/pbr.cc"} \caption{\legionbook{Partitions/partition\_by\_restriction/pbr.cc}} \label{fig:pbr} \end{figure} @@ -199,9 +193,7 @@ \section{Set-Based Partitions} \begin{figure} - {\small - \lstinputlisting[linerange={21-58}]{Examples/Partitions/sets/sets.cc} - } + \lstinputlisting[language=C++,linerange={21-58}]{Examples/Partitions/sets/sets.cc} \caption{\legionbook{Partitions/sets/sets.cc}} \label{fig:sets} \end{figure} @@ -235,9 +227,7 @@ \section{Image Partitions} The rest of the program (lines 41-45) sums the value field of the destination partition's subregions (which as in other examples has the same value 1 for every element). Since the 1-1 pointer relationship copies the coloring exactly from source to destination and the source was an equal partition, the sums printed for each subregion are the same. \begin{figure} - {\small - \lstinputlisting[linerange={17-76}]{Examples/Partitions/image/image.cc} - } + \lstinputlisting[language=C++,linerange={17-76}]{Examples/Partitions/image/image.cc} \caption{\legionbook{Partitions/image/image.cc}} \label{fig:image} \end{figure} @@ -268,9 +258,7 @@ \section{Pre-Image Partitions} \begin{figure} - {\small - \lstinputlisting[linerange={17-74}]{"Examples/Partitions/pre_image/preimage.cc"} - } + \lstinputlisting[language=C++,linerange={17-74}]{"Examples/Partitions/pre_image/preimage.cc"} \caption{\legionbook{Partitions/pre\_image/preimage.cc}} \label{fig:preimage} \end{figure} diff --git a/regions.tex b/regions.tex index 62c0d8b..e0a054c 100644 --- a/regions.tex +++ b/regions.tex @@ -56,8 +56,7 @@ \chapter{Regions} region. \begin{figure} -{\small - \lstinputlisting[linerange={19-38}]{Examples/Regions/logicalregions/logicalregions.cc}} +\lstinputlisting[language=C++,linerange={19-38}]{Examples/Regions/logicalregions/logicalregions.cc} \caption{\legionbook{Regions/logicalregions/logicalregions.cc}} \label{fig:lr1} \end{figure} @@ -77,8 +76,7 @@ \section{Physical Instances, Region Requirements, Privileges and Accessors} Chapter~\ref{chap:coherence}. \begin{figure} -{\small - \lstinputlisting[linerange={31-39}]{Examples/Regions/physicalregions/physicalregions.cc}} +\lstinputlisting[language=C++,linerange={31-39}]{Examples/Regions/physicalregions/physicalregions.cc} \caption{Task launches from \legionbook{Regions/physicalregions/physicalregions.cc.}} \label{fig:privileges} \end{figure} @@ -142,8 +140,7 @@ \section{Physical Instances, Region Requirements, Privileges and Accessors} accessed by the subtask. \begin{figure} - {\small - \lstinputlisting[linerange={63-75}]{Examples/Regions/physicalregions/physicalregions.cc}} + \lstinputlisting[language=C++,linerange={63-75}]{Examples/Regions/physicalregions/physicalregions.cc} \caption{Region accessors from \legionbook{Regions/physicalregions/physicalregions.cc}.} \label{fig:accessors} \end{figure} @@ -203,8 +200,7 @@ \section{Fill Fields} the runtime that fills every occurrence of {\tt FIELD\_A} with a default value. \begin{figure} - {\small - \lstinputlisting[linerange={28-31}]{Examples/Regions/fillfields/fillfields.cc}} + \lstinputlisting[language=C++,linerange={28-31}]{Examples/Regions/fillfields/fillfields.cc} \caption{\legionbook{Regions/fillfields/fillfields.cc}} \label{fig:fill} \end{figure} @@ -256,9 +252,9 @@ \section{Inline Launchers} \begin{figure} {\small - \lstinputlisting[linerange={26-29}]{Examples/Regions/inlinemapping/inlinemapping.cc} + \lstinputlisting[language=C++,linerange={26-29}]{Examples/Regions/inlinemapping/inlinemapping.cc} ... lines omitted ...\\ - \lstinputlisting[linerange={43-44}]{Examples/Regions/inlinemapping/inlinemapping.cc}} + \lstinputlisting[language=C++,linerange={43-44}]{Examples/Regions/inlinemapping/inlinemapping.cc}} \caption{\legionbook{Regions/inlinemapping/inlinemapping.cc}} \label{fig:inlinelaunch} \end{figure} diff --git a/tasks.tex b/tasks.tex index a6798b7..0e95b4f 100644 --- a/tasks.tex +++ b/tasks.tex @@ -1,21 +1,6 @@ \chapter{Tasks} \label{chap:tasks} -% Set up the listing configuration for everything -\lstset{ - captionpos=b, - language=C++, - basicstyle=\scriptsize, - numbers=left, - numberstyle=\tiny, - columns=fullflexible, - stepnumber=1, - escapechar=\#, - keepspaces=true, - literate={<}{{$\langle$}}1 {>}{{$\rangle$}}1, - %xleftmargin=15pt, -} - The Legion runtime is a \Cpp\ library, and Legion programs are just C++ programs that use the Legion runtime API. One important consequence of this design is that almost all Legion decisions @@ -39,22 +24,18 @@ \chapter{Tasks} \end{itemize} - \begin{figure} - {\small - \lstinputlisting{Examples/Tasks/sum/sum.cc} - } +\lstinputlisting[language=C++]{Examples/Tasks/sum/sum.cc} \caption{\legionbook{Tasks/sum/sum.cc}} \label{fig:simple} \end{figure} Figure~\ref{fig:simple} shows a very simple, but complete, Legion program for summing the first 1000 positive integers (also available as {\tt sum.cc} in \legionbook{Tasks}). -This example, like every other example in this manual, can be run by first setting an environment variable to point to the Legion runtime -\begin{verbatim} -export LG_RT_DIR="...path to legion directory.../legion/runtime" -\end{verbatim} -and then typing {\tt make} in the directory containing the example. +This example, like every other example in this manual, can be run by completing the installation instructions in Chapter~\ref{chap:start} and then running: +\begin{lstlisting}[language=bash,style=inline] +./build/sum +\end{lstlisting} At a high level, every Legion program has three components: \begin{itemize} @@ -131,9 +112,7 @@ \section{Subtasks} \begin{figure} - {\small - \lstinputlisting{Examples/Tasks/subtasks/subtasks.cc} - } +\lstinputlisting[language=C++]{Examples/Tasks/subtasks/subtasks.cc} \caption{\legionbook{Tasks/subtasks/subtasks.cc}} \label{fig:subtask} \end{figure} @@ -199,8 +178,7 @@ \section{Futures} \label{sec:futures} \begin{figure} - {\small - \lstinputlisting[linerange={14-48}]{Examples/Tasks/futures/futures.cc}} +\lstinputlisting[language=C++,linerange={14-48}]{Examples/Tasks/futures/futures.cc} \caption{\legionbook{Tasks/futures/futures.cc}} \label{fig:futures} \end{figure} @@ -270,31 +248,31 @@ \section{Points, Rectangles and Domains} A {\em point} is an n-tuple of integers. The {\tt Point} constructor, which is templated on the dimension $n$, is used to create points: -\begin{verbatim} +\begin{lstlisting}[language=C++,style=inline] Point<1> one(1); // The 1 dimensional point <1> Point<1> two(2); // The 1 dimensional point <2> Point<2> zeroes(0,0); // The 2 dimensional point <0,0> Point<2> twos(2,2); // The 2 dimensional point <2,2> Point<2> threes(3,3); // The 2 dimensional point <3,3> Point<3> fours(4,4,4); // The 3 dimensional point <4,4,4> -\end{verbatim} +\end{lstlisting} There are many operations defined on points. For example, points can be summed: -\begin{verbatim} +\begin{lstlisting}[language=C++,style=inline] twos + threes // the point <5,5> -\end{verbatim} +\end{lstlisting} and one can take the dot product of two points: -\begin{verbatim} +\begin{lstlisting}[language=C++,style=inline] twos.dot(threes) // the integer 12 -\end{verbatim} +\end{lstlisting} The following are true: -\begin{verbatim} +\begin{lstlisting}[language=C++,style=inline] twos == twos twos != threes -\end{verbatim} +\end{lstlisting} A pair of points $a$ and $b$ defines a {\em rectangle} that includes all the points that are greater than or equal to $a$ and less than or equal to $b$. For example: -\begin{verbatim} +\begin{lstlisting}[language=C++,style=inline] // the points <0,0> <0,1> <0,2> <0,3> // <1,0> <1,1> <1,2> <1,3> // <2,0> <2,1> <2,2> <2,3> @@ -304,19 +282,19 @@ \section{Points, Rectangles and Domains} // the points <2,2> <2,3> // <3,2> <3,3> Rect<2> small(twos,threes); -\end{verbatim} +\end{lstlisting} There are also many operations defined on rectangles. A few examples, all of which evaluate to true: -\begin{verbatim} +\begin{lstlisting}[language=C++,style=inline] big != small big.contains(small) small.overlaps(big) small.intersection(big) == small -\end{verbatim} +\end{lstlisting} Note that the intersection of two rectangles is always a rectangle. A {\em domain} is an alternative type for rectangles. A {\tt Rect} can be converted to a {\tt Domain}: -\begin{verbatim} +\begin{lstlisting}[language=C++,style=inline] Domain bigdomain = big; -\end{verbatim} +\end{lstlisting} The difference between the two types is that {\tt Rect}s are templated on the dimension of the rectangle, while {\tt Domains} are not. Legion runtime methods generally take {\tt Domain} arguments and use {\tt Domain}s internally, but for application code the extra type checking provided by the {\tt Rect} type (which ensures that the operations are applied to {\tt Rect} arguments @@ -329,9 +307,9 @@ \section{Points, Rectangles and Domains} Again, the difference between the two types is that the {\tt Point} class is templated on the number of dimensions while {\tt DomainPoint} is not. For Legion methods that require a {\tt DomainPoint}, there is a function to convert a {\tt Point}: -\begin{verbatim} +\begin{lstlisting}[language=C++,style=inline] DomainPoint dtwos = twos; -\end{verbatim} +\end{lstlisting} As before, most Legion runtime calls take {\tt DomainPoints}, but programmers should probably prefer using the {\tt Point} type for the extra type checking provided. @@ -351,8 +329,7 @@ \section{Index Launches} where all of the task instances can run in parallel. \begin{figure} -{\small -\lstinputlisting[linerange={47-90}]{Examples/Tasks/indexlaunch/indexlaunch.cc}} +\lstinputlisting[language=C++,linerange={47-90}]{Examples/Tasks/indexlaunch/indexlaunch.cc} \caption{\legionbook{Tasks/indexlaunch/indexlaunch.cc}} \label{fig:indexlaunch} \end{figure}