#LyX 2.4 created this file. For more info see https://www.lyx.org/
\lyxformat 620
\begin_document
\begin_header
\save_transient_properties true
\origin unavailable
\textclass ../ac-manual
\use_default_options false
\begin_modules
tcolorbox
\end_modules
\maintain_unincluded_children no
\language english
\language_package default
\inputencoding auto-legacy
\fontencoding auto
\font_roman "times" "default"
\font_sans "helvet" "default"
\font_typewriter "courier" "default"
\font_math "auto" "auto"
\font_default_family sfdefault
\use_non_tex_fonts false
\font_sc false
\font_roman_osf false
\font_sans_osf false
\font_typewriter_osf false
\font_sf_scale 100 100
\font_tt_scale 100 100
\use_microtype true
\use_dash_ligatures true
\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\float_placement class
\float_alignment class
\paperfontsize 12
\spacing onehalf
\use_hyperref true
\pdf_title "AspectC++ First Steps"
\pdf_author "The AspectC++ Developers"
\pdf_subject "Documentation"
\pdf_keywords "AOP, AspectC++, ac++"
\pdf_bookmarks true
\pdf_bookmarksnumbered false
\pdf_bookmarksopen false
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder false
\pdf_colorlinks true
\pdf_backref false
\pdf_pdfusetitle true
\pdf_quoted_options "urlcolor=blue"
\papersize default
\use_geometry true
\use_package amsmath 1
\use_package amssymb 1
\use_package cancel 1
\use_package esint 0
\use_package mathdots 1
\use_package mathtools 1
\use_package mhchem 1
\use_package stackrel 1
\use_package stmaryrd 1
\use_package undertilde 1
\cite_engine basic
\cite_engine_type default
\biblio_style plain
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\justification true
\use_refstyle 0
\use_formatted_ref 0
\use_minted 0
\use_lineno 0
\index Index
\shortcut idx
\color #008000
\end_index
\leftmargin 2.5cm
\topmargin 3cm
\rightmargin 3.5cm
\bottommargin 4cm
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\is_math_indent 0
\math_numbering_side default
\quotes_style english
\dynamic_quotes 0
\papercolumns 1
\papersides 2
\paperpagestyle fancy
\tablestyle default
\listings_params "basicstyle={\ttfamily},showstringspaces=false,upquote=true"
\tracking_changes false
\output_changes false
\change_bars false
\postpone_fragile_content false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\docbook_table_output 0
\docbook_mathml_prefix 1
\end_header

\begin_body

\begin_layout Title

\emph on
AspectC++ First Steps
\end_layout

\begin_layout Author

\size largest
The AspectC++ Developers
\begin_inset VSpace 3mm
\end_inset


\begin_inset Newline newline
\end_inset


\size default
Version 2.5
\end_layout

\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\begin_inset Note Note
status open

\begin_layout Plain Layout
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
clearpage
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Section
Getting Started
\end_layout

\begin_layout Standard
Let's get in touch with AspectC++.
 This document provides a step-by-step introduction to:
\end_layout

\begin_layout Itemize
Installing the AspectC++ compiler on Linux,
 macOS,
 and Windows (
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Installation"
plural "false"
caps "false"
noprefix "false"
nolink "false"

\end_inset

)
\end_layout

\begin_layout Itemize
Writing a program that traces function execution (
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Tracing-Aspect"
plural "false"
caps "false"
noprefix "false"
nolink "false"

\end_inset

)
\end_layout

\begin_layout Itemize
Using the CMake build system to manage AspectC++ projects (
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:CMake"
plural "false"
caps "false"
noprefix "false"
nolink "false"

\end_inset

)
\end_layout

\begin_layout Itemize
Generating binary code for different processor architectures with a cross compiler (
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Cross-Compilation"
plural "false"
caps "false"
noprefix "false"
nolink "false"

\end_inset

)
\end_layout

\begin_layout Standard
\begin_inset Note Note
status open

\begin_layout Plain Layout
This document is intended to be used as a reference book for the AspectC++ language elements.
 It describes in-depth the use and meaning of each element providing examples.
 For experienced users the contents of this document are summarized in the 
\begin_inset CommandInset href
LatexCommand href
name "AspectC++ Quick Reference"
target "http://www.aspectc.org/doc/ac-quickref.pdf"
literal "false"

\end_inset

.
 
\begin_inset Note Note
status open

\begin_layout Plain Layout
A step-by-step introduction how to program with AspectC++ is given in the 
\begin_inset CommandInset href
LatexCommand href
name "AspectC++ Programming Guide"
target "http://www.aspectc.org/Documentation.5.0.html"
literal "false"

\end_inset


\begin_inset Foot
status collapsed

\begin_layout Plain Layout
Sorry,
 but the Programming Guide is not written yet 
\family typewriter
:-(
\end_layout

\end_inset

.
\end_layout

\end_inset

Detailed information about the AspectC++ compiler 
\family typewriter
\series bold
ac++
\family default
\series default
 can be looked up in the 
\begin_inset CommandInset href
LatexCommand href
name "AspectC++ Compiler Manual"
target "http://www.aspectc.org/doc/ac-compilerman.pdf"
literal "false"

\end_inset

.
 
\end_layout

\end_inset


\end_layout

\begin_layout Section
Installation
\begin_inset CommandInset label
LatexCommand label
name "sec:Installation"

\end_inset


\end_layout

\begin_layout Standard
The first step is to install AspectC++.
 We recommend downloading the latest release from 
\begin_inset Flex URL
status open

\begin_layout Plain Layout

https://www.aspectc.org
\end_layout

\end_inset

 in the Download section.
\end_layout

\begin_layout Subsection
Installing AspectC++ on Linux
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
thickness "0.4pt"
separation "3pt"
shadowsize "4pt"
framecolor "default"
backgroundcolor "none"
status open

\begin_layout Plain Layout
Note:
 If you are using Debian,
 Ubuntu,
 or derivatives,
 you can install AspectC++ readily from the distribution's repository by typing the following command in a terminal:
 
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

sudo apt install aspectc++
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout
That's all!
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you use a non-Debian/Ubuntu Linux distribution or want to install the most recent version of AspectC++,
 you can choose between a 32-bit (Linux/x86) and 64-bit (Linux/x86_64) version.
 Open a terminal and enter the following command:
 
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

uname -m
\end_layout

\end_inset

If the output is 
\family typewriter
x86_64
\family default
,
 download the 64-bit version (Linux/x86_64) from 
\begin_inset Flex URL
status open

\begin_layout Plain Layout

https://www.aspectc.org
\end_layout

\end_inset

.
 Otherwise,
 download the 32-bit version (Linux/x86).
 Open a terminal,
 change to the download directory and unpack the downloaded file:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

tar xzvf ac-bin-linux-*.tar.gz
\end_layout

\end_inset

The unpacked contents are stored in the folder 
\family typewriter
aspect++/
\family default
.
 The next step is to add that folder to your 
\family typewriter
PATH
\family default
 system variable.
 Assuming you have downloaded AspectC++ to a folder named 
\family typewriter
Downloads/
\family default
 in your home directory
\begin_inset space ~
\end_inset

(
\family typewriter
$HOME
\family default
),
 just type the following command in the terminal:
 
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

export PATH=$HOME/Downloads/aspectc++/:$PATH
\end_layout

\end_inset

Add the line from above to 
\family typewriter
$HOME/.bashrc
\family default
 or the like to set this path permanently.
\end_layout

\begin_layout Standard
Linux users should also install the GNU C++ compiler (g++).
 If you are using Debian,
 Ubuntu,
 or derivatives,
 you can install the 
\family typewriter
build-essential
\family default
 package from the distribution's repository.
\end_layout

\begin_layout Subsection
Installing AspectC++ on macOS
\end_layout

\begin_layout Standard
On macOS,
 go to 
\begin_inset Flex URL
status open

\begin_layout Plain Layout

https://www.aspectc.org
\end_layout

\end_inset

 and download the respective release file.
 Open a terminal,
 change to the download directory and unpack the downloaded file:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

tar xzvf ac-bin-macosx-*.tar.gz
\end_layout

\end_inset

The unpacked contents are stored in the folder 
\family typewriter
aspect++/
\family default
.
 The next step is to add that folder to your 
\family typewriter
PATH
\family default
 system variable.
 Assuming you have downloaded AspectC++ to a folder named 
\family typewriter
Downloads/
\family default
 in your home directory
\begin_inset space ~
\end_inset

(
\family typewriter
$HOME
\family default
),
 just type the following command in the terminal:
 
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

export PATH=$HOME/Downloads/aspectc++/:$PATH
\end_layout

\end_inset

Add the line from above to 
\family typewriter
$HOME/.zshrc
\family default
 or the like to set this path permanently.
\end_layout

\begin_layout Standard
On macOS,
 you should also install the Clang C++ (
\family typewriter
clang++
\family default
) compiler by using the following command:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

xcode-select --install
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Installing AspectC++ on Windows
\end_layout

\begin_layout Standard
On Windows,
 go to 
\begin_inset Flex URL
status open

\begin_layout Plain Layout

https://www.aspectc.org
\end_layout

\end_inset

 and download the respective release file.
 Open the file manager,
 change to the download directory and unpack the downloaded zip file.
 The unpacked contents are stored in the folder 
\family typewriter
aspect++
\backslash

\family default
.
 The next step is to add that folder to your 
\family typewriter
PATH
\family default
 system variable:
\end_layout

\begin_layout Enumerate
Open the Windows start menu (Start) and search for 
\family typewriter
\series bold
environment variables
\family default
\series default
 and open it.
\end_layout

\begin_layout Enumerate
Click on the button 
\begin_inset Quotes eld
\end_inset

Environment Variables
\begin_inset Quotes erd
\end_inset

.
\end_layout

\begin_layout Enumerate
In the section 
\begin_inset Quotes eld
\end_inset

User variables
\begin_inset Quotes erd
\end_inset

 select the item 
\family typewriter
\series bold
Path
\family default
\series default
 and click on the 
\begin_inset Quotes eld
\end_inset

Edit
\begin_inset Quotes erd
\end_inset

 button.
\end_layout

\begin_layout Enumerate
Click on the 
\begin_inset Quotes eld
\end_inset

New
\begin_inset Quotes erd
\end_inset

 button.
 Assuming you have downloaded AspectC++ to a folder named 
\family typewriter
Downloads
\backslash

\family default
 in your home directory on drive 
\family typewriter
C:
\backslash

\family default
,
 enter the following path:
 
\family typewriter
C:
\backslash
Users
\backslash
<Your Name>
\backslash
Downloads
\backslash
aspectc++
\end_layout

\begin_layout Enumerate
Click on the 
\begin_inset Quotes eld
\end_inset

OK
\begin_inset Quotes erd
\end_inset

 button of every opened window.
\end_layout

\begin_layout Standard
Windows users should also install MSYS2 and the GNU C/C++ compiler (GCC).
 Go to 
\begin_inset Flex URL
status open

\begin_layout Plain Layout

https://www.msys2.org/
\end_layout

\end_inset

 and follow the instructions for installing MSYS2.
 In particular,
 take care of installing GCC using 
\emph on
pacman
\emph default
 as described there.
 You should add the installation path of that GCC to your 
\family typewriter
PATH
\family default
 system variable:
\end_layout

\begin_layout Enumerate
Open the Windows start menu (Start) and search for 
\family typewriter
\series bold
environment variables
\family default
\series default
 and open it.
\end_layout

\begin_layout Enumerate
Click on the button 
\begin_inset Quotes eld
\end_inset

Environment Variables
\begin_inset Quotes erd
\end_inset

.
\end_layout

\begin_layout Enumerate
In the section 
\begin_inset Quotes eld
\end_inset

System variables
\begin_inset Quotes erd
\end_inset

 select the item 
\family typewriter
\series bold
Path
\family default
\series default
 and click on the 
\begin_inset Quotes eld
\end_inset

Edit
\begin_inset Quotes erd
\end_inset

 button.
\end_layout

\begin_layout Enumerate
Click on the 
\begin_inset Quotes eld
\end_inset

New
\begin_inset Quotes erd
\end_inset

 button.
 Assuming you have installed MSYS2 to 
\family typewriter
C:
\backslash
msys64
\backslash

\family default
,
 enter the following path:
 
\family typewriter
C:
\backslash
msys64
\backslash
ucrt64
\backslash
bin
\end_layout

\begin_layout Enumerate
Click on the 
\begin_inset Quotes eld
\end_inset

OK
\begin_inset Quotes erd
\end_inset

 button of every opened window.
\end_layout

\begin_layout Subsection
Troubleshooting
\end_layout

\begin_layout Standard
To check your AspectC++ installation,
 open a new terminal (Linux and macOS) or PowerShell (Windows) and enter the following command:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

ac++ --version && ag++ --version
\end_layout

\end_inset

The output should show the version numbers and build dates for your installed AspectC++ release,
 in the following format:
 
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

ac++ x.y (<date>,
 clang a.b.c)
\end_layout

\begin_layout Plain Layout

ag++ u.w  built:
 <date>
\end_layout

\end_inset

If you see these numbers and dates,
 you have installed AspectC++ successfully!
 Otherwise,
 check whether AspectC++ is in your 
\family typewriter
PATH
\family default
 system variable.
\begin_inset Newline newline
\end_inset

On Linux and macOS,
 examine the output of the following command:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

echo $PATH
\end_layout

\end_inset

On Windows using PowerShell,
 examine the output of:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

echo $env:Path
\end_layout

\end_inset


\end_layout

\begin_layout Section
Tracing Aspect
\begin_inset CommandInset label
LatexCommand label
name "sec:Tracing-Aspect"

\end_inset


\end_layout

\begin_layout Standard
After installing AspectC++,
 it is time to write your first AspectC++ program.
 We will start by making a directory to store AspectC++ code.
 We propose to create a new directory called 
\family typewriter
tracing_aspectc++
\family default
 in your home directory.
 Open a new terminal on Linux,
 macOS,
 or Windows (using PowerShell) and enter the following commands:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

mkdir $HOME/tracing_aspectc++
\end_layout

\begin_layout Plain Layout

cd $HOME/tracing_aspectc++
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Inside this directory,
 create a new source file and call it 
\family typewriter
factorial.cpp
\family default
.
 Open that file and enter the following C++ code:
\end_layout

\begin_layout Standard
\begin_inset Flex Color Box
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "language={C++}"
inline false
status open

\begin_layout Plain Layout

#include <iostream>
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

unsigned int factorial(unsigned int n) {
\end_layout

\begin_layout Plain Layout

   return (n > 1) ?
  n * factorial(n - 1) :
 1;
\end_layout

\begin_layout Plain Layout

}
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

int main() {
\end_layout

\begin_layout Plain Layout

    std::cout << factorial(3) << " == 3!" << std::endl;
\end_layout

\begin_layout Plain Layout

    return 0;
\end_layout

\begin_layout Plain Layout

}
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Next,
 make a new aspect header file and call it 
\family typewriter
tracing.ah
\family default
.
 By convention,
 AspectC++ header files always end with the
\family typewriter

\begin_inset space ~
\end_inset

.ah
\family default
 extension.
 Open the 
\family typewriter
tracing.ah
\family default
 file with your text editor and enter the following AspectC++ code:
\end_layout

\begin_layout Standard
\begin_inset Flex Color Box
status open

\begin_layout Plain Layout
\begin_inset listings
lstparams "language={[Aspect]C++}"
inline false
status open

\begin_layout Plain Layout

#ifndef __TRACING_AH__
\end_layout

\begin_layout Plain Layout

#define __TRACING_AH__
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

#include <iostream>
\end_layout

\begin_layout Plain Layout

#include <string>
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

aspect Tracing {
\end_layout

\begin_layout Plain Layout

    unsigned int level = 0;
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

    advice execution("% ...::%(...)") :
 before() {
\end_layout

\begin_layout Plain Layout

        std::cout << std::string(level++,
 ' ') << "> "
\end_layout

\begin_layout Plain Layout

            << JoinPoint::signature() << std::endl;
\end_layout

\begin_layout Plain Layout

    }
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

    advice execution("% ...::%(...)") :
 after() {
\end_layout

\begin_layout Plain Layout

        level--;
\end_layout

\begin_layout Plain Layout

    }
\end_layout

\begin_layout Plain Layout

};
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

#endif
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Save both files and go back to your terminal 
\begin_inset Note Note
status open

\begin_layout Plain Layout
window 
\end_layout

\end_inset

in the 
\family typewriter
$HOME/tracing_aspectc++
\family default
 directory.
 Enter the following command to compile both files to an executable program:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

ag++ factorial.cpp
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To run the program on Linux or macOS,
 type the following command in the terminal:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

./a.out
\end_layout

\end_inset


\end_layout

\begin_layout Standard
On Windows,
 enter:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

.
\backslash
a.exe
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Now,
 you should see the output of the program:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

> int main()
\end_layout

\begin_layout Plain Layout

 > unsigned int factorial(unsigned int)
\end_layout

\begin_layout Plain Layout

  > unsigned int factorial(unsigned int)
\end_layout

\begin_layout Plain Layout

   > unsigned int factorial(unsigned int)
\end_layout

\begin_layout Plain Layout

6 == 3!
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The file 
\family typewriter
factorial.cpp
\family default
 just computes the factorial of three and prints it on the final line (6 == 3!).
 The aspect header file 
\family typewriter
tracing.ah
\family default
 makes the program to trace the C++ function execution and,
 therefore,
 prints the first four lines (beginning with 
\family typewriter
>
\family default
).
 That is,
 the function 
\family typewriter
main()
\family default
 runs first,
 and then the function 
\family typewriter
factorial(unsigned int)
\family default
 gets called three times recursively.
 In short,
 the AspectC++ expression 
\family typewriter
advice
\begin_inset space ~
\end_inset

execution("%
\begin_inset space ~
\end_inset

...::%(...)")
\family default
 captures the 
\emph on
execution
\emph default
 of any function by the wildcard expression
\family typewriter
 "%"
\family default
 for return type and function name,
 and the wildcard expression 
\family typewriter
"..."
\family default
 for any sequence of scopes and function arguments.
 The aspect file generates the tracing output eventually by AspectC++'s built-in function 
\family typewriter
JoinPoint::signature()
\family default
,
 which returns a formatted string per captured function that describes the function's return type,
 its name,
 and argument types.
\end_layout

\begin_layout Subsection
Project Directory Tree
\end_layout

\begin_layout Standard
By default,
 the AspectC++ compiler uses the current working directory
\begin_inset space ~
\end_inset


\family typewriter
./
\family default
 as 
\emph on
project directory tree
\emph default
.
 That is,
 the AspectC++ compiler searches recursively there for aspect header files and applies the advice to all C++ source and header files in that directory.
 The 
\emph on
project directory tree
\emph default
 can also be specified on the command line explicitly.
 In our example,
 the following two commands are equivalent:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

ag++ factorial.cpp
\end_layout

\begin_layout Plain Layout

ag++ -p $HOME/tracing_aspectc++ factorial.cpp
\end_layout

\end_inset


\end_layout

\begin_layout Standard
This means,
 that the compiler applies all pieces of advice to source and header files in the 
\family typewriter
$HOME/tracing_aspectc++
\family default
 directory only.
 In particular,
 the compiler applies no advice to functions of the C/C++ standard library,
 because the standard library files are typically stored elsewhere.
 Therefore,
 the tracing aspect in our example does not print the 
\family typewriter
operator
\begin_inset space ~
\end_inset

<<
\family default
 function on the 
\family typewriter
std::cout
\family default
 object of the standard library.
\end_layout

\begin_layout Subsection
Aspect Header Files
\end_layout

\begin_layout Standard
As explained in the previous section,
 the AspectC++ compiler by default searches recursively for aspect header files in the 
\emph on
project directory tree
\emph default
.
 You can alternatively specify the aspect header files explicitly on the command line with the 
\family typewriter
-a
\family default
 option.
 In our example,
 the following two commands are equivalent:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

ag++ -p $HOME/tracing_aspectc++ factorial.cpp
\end_layout

\begin_layout Plain Layout

ag++ -p $HOME/tracing_aspectc++ -a tracing.ah factorial.cpp
\end_layout

\end_inset


\end_layout

\begin_layout Standard
You can use the 
\family typewriter
-a
\family default
 option multiple times if there are multiple aspect files to be considered.
 You can use 
\family typewriter
-a
\begin_inset space ~
\end_inset

0
\family default
 for not considering any aspect file at all.
\end_layout

\begin_layout Section
Managing Dependencies with CMake
\begin_inset CommandInset label
LatexCommand label
name "sec:CMake"

\end_inset


\end_layout

\begin_layout Standard
The CMake build system is a tool to manage growing software projects.
 You can use CMake to invoke the AspectC++ compiler and to manage include dependencies automatically.
 Install CMake as described in the download section of 
\begin_inset Flex URL
status open

\begin_layout Plain Layout

https://cmake.org
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
Assuming you have stored the two files 
\family typewriter
factorial.cpp
\family default
 and 
\family typewriter
tracing.ah
\family default
 in the directory 
\family typewriter
$HOME/tracing_aspectc++
\family default
 as explained in the previous section,
 you can manage that directory with CMake by creating a new text file there and name it 
\family typewriter
CMakeLists.txt
\family default
.
 Open the 
\family typewriter
CMakeLists.txt
\family default
 file with your text editor and enter the following CMake commands:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language={cmake}"
inline false
status open

\begin_layout Plain Layout

cmake_minimum_required (VERSION 3.20)
\end_layout

\begin_layout Plain Layout

project ("AspectC++ Tracing Example")
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

set(CMAKE_CXX_COMPILER "ag++")
\end_layout

\begin_layout Plain Layout

set(CMAKE_CXX_FLAGS "--Xweaver 
\backslash

\end_layout

\begin_layout Plain Layout

-p $ENV{HOME}/tracing_aspectc++ --Xcompiler")
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

file(GLOB cxx_files "*.cpp")
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

add_executable(factorial ${cxx_files})
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Save the file and open a terminal (Linux and macOS) or PowerShell (Windows).
 Create a new out-of-source build directory:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

mkdir $HOME/tracing_aspectc++/build
\end_layout

\begin_layout Plain Layout

cd $HOME/tracing_aspectc++/build
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The next step is to run 
\family typewriter
cmake
\family default
 in your terminal to generate the build system:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

cmake ..
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Then,
 you can use it to compile and link the executable file 
\family typewriter
factorial
\family default
.
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

cmake --build .
\end_layout

\end_inset


\end_layout

\begin_layout Standard
CMake takes care of managing include dependencies.
 That is,
 when a source,
 header,
 or aspect header files changes,
 you can use the previous command to rebuild only the affected set of files.
 AspectC++ currently considers every aspect header file as include dependency.
 That is,
 changes to one aspect header file cause every source file to be rebuilt.
 Technically,
 AspectC++ generates the dependency information just like 
\family typewriter
g++
\family default
 with the 
\family typewriter
-MMD
\family default
 and 
\family typewriter
-MD
\family default
 command line options,
 respectively.
\end_layout

\begin_layout Section
Cross Compilation
\begin_inset CommandInset label
LatexCommand label
name "sec:Cross-Compilation"

\end_inset


\end_layout

\begin_layout Standard
The AspectC++ compiler comes with two tools:
 
\family typewriter
ag++
\family default
 and 
\family typewriter
ac++
\family default
.
 The 
\family typewriter
ac++
\family default
 tool implements a source-to-source compiler that translates AspectC++ source code to plain C++ source code.
 Thus,
 
\family typewriter
ac++
\family default
 does not directly generate the executable.
 You have to use a C++ compiler,
 such as the GNU C++ compiler (
\family typewriter
g++
\family default
).
 For that reason,
 there is the 
\family typewriter
ag++
\family default
 tool,
 which implements a wrapper for both 
\family typewriter
g++
\family default
 and 
\family typewriter
ac++
\family default
.
 That is,
 
\family typewriter
ag++
\family default
 invokes 
\family typewriter
ac++
\family default
 first to carry out the source-to-source transformation to a temporary file,
 and then invokes 
\family typewriter
g++
\family default
 to generate the executable.
 Because of that,
 you typically should 
\emph on
not
\emph default
 invoke 
\family typewriter
ac++
\family default
 manually and should use 
\family typewriter
ag++
\family default
 instead.
\end_layout

\begin_layout Standard
By default,
 
\family typewriter
ag++
\family default
 invokes the host 
\family typewriter
g++
\family default
 compiler to generate the executable.
 However,
 you can also make 
\family typewriter
ag++
\family default
 use a 
\emph on
cross compiler
\emph default
.
 You can compile the example program from 
\begin_inset CommandInset ref
LatexCommand formatted
reference "sec:Tracing-Aspect"
plural "false"
caps "false"
noprefix "false"
nolink "false"

\end_inset

,
 for instance,
 to ARM microcontrollers using the GNU ARM embedded toolchain with the following command:
\end_layout

\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open

\begin_layout Plain Layout

ag++ --c_compiler arm-none-eabi-g++ 
\backslash

\end_layout

\begin_layout Plain Layout

--Xcompiler -specs=nosys.specs factorial.cpp
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\family typewriter
ag++
\family default
 
\begin_inset Note Note
status open

\begin_layout Plain Layout
command line 
\end_layout

\end_inset

option 
\family typewriter
--c_compiler
\family default
 specifies that the 
\family typewriter
arm-none-eabi-g++
\family default
 compiler (if installed) shall be used to generate the executable.
 In addition,
 the above command uses the 
\family typewriter
--Xcompiler
\family default
 option to tell 
\family typewriter
ag++
\family default
 that every subsequent command line option shall be passed to the C++ (cross) compiler only.
 The other way around,
 any command line option after 
\family typewriter
--Xweaver
\family default
 will passed to the ac++ tool only.
 You should pass special options to the cross compiler,
 such as 
\family typewriter
-specs=nosys.specs
\family default
 in our example,
 by placing them after the 
\family typewriter
--Xcompiler
\family default
 option.
\end_layout

\end_body
\end_document
