├── .clang-format ├── CMakeLists.txt ├── Info.plist.in ├── LICENSE.TXT ├── Makefile ├── README.md ├── include ├── PrintableTemplightEntries.h ├── TemplightAction.h ├── TemplightDebugger.h ├── TemplightEntryPrinter.h ├── TemplightProtobufWriter.h ├── TemplightTracer.h └── ThinProtobuf.h ├── lib ├── CMakeLists.txt ├── TemplightAction.cpp ├── TemplightDebugger.cpp ├── TemplightEntryPrinter.cpp ├── TemplightProtobufWriter.cpp └── TemplightTracer.cpp ├── templight_clang_patch.diff ├── templight_clang_patch_with_context.diff ├── templight_clang_version.txt ├── templight_driver.cpp ├── templight_messages.proto ├── templight_symlink.cmake ├── test ├── CMakeLists.txt ├── Unit │ ├── lit.cfg.py │ └── lit.site.cfg.py.in ├── lit.cfg ├── lit.site.cfg.in ├── templight-driver-flag.cpp └── templight_as_compiler.cpp ├── unittests ├── CMakeLists.txt └── TemplightActionTest.cpp └── utils ├── ExtraWriters ├── TemplightExtraWriters.cpp └── TemplightExtraWriters.h ├── ProtobufReader ├── TemplightProtobufReader.cpp └── TemplightProtobufReader.h ├── create_patch.sh └── format.sh /.clang-format: -------------------------------------------------------------------------------- 1 | BasedOnStyle: LLVM 2 | -------------------------------------------------------------------------------- /CMakeLists.txt: -------------------------------------------------------------------------------- 1 | 2 | set( LLVM_LINK_COMPONENTS 3 | ${LLVM_TARGETS_TO_BUILD} 4 | Analysis 5 | CodeGen 6 | Core 7 | IPO 8 | InstCombine 9 | Instrumentation 10 | MC 11 | MCParser 12 | ObjCARCOpts 13 | Option 14 | ScalarOpts 15 | Support 16 | TargetParser 17 | TransformUtils 18 | Vectorize 19 | ) 20 | 21 | include_directories(BEFORE 22 | ${CMAKE_CURRENT_SOURCE_DIR}/include 23 | ) 24 | add_subdirectory(lib) 25 | 26 | add_clang_executable(templight 27 | templight_driver.cpp 28 | ) 29 | 30 | target_link_libraries(templight 31 | PRIVATE 32 | clangBasic 33 | clangDriver 34 | clangFrontend 35 | clangFrontendTool 36 | clangSerialization 37 | clangTemplight 38 | ) 39 | 40 | set_target_properties(templight PROPERTIES VERSION ${CLANG_EXECUTABLE_VERSION}) 41 | 42 | add_dependencies(templight clang-headers) 43 | 44 | if(UNIX) 45 | set(CLANGXX_LINK_OR_COPY create_symlink) 46 | # Create a relative symlink 47 | set(templight_binary "templight${CMAKE_EXECUTABLE_SUFFIX}") 48 | else() 49 | set(CLANGXX_LINK_OR_COPY copy) 50 | set(templight_binary "${LLVM_RUNTIME_OUTPUT_INTDIR}/templight${CMAKE_EXECUTABLE_SUFFIX}") 51 | endif() 52 | 53 | # Create the templight++ symlink in the build directory. 54 | set(templight_pp "${LLVM_RUNTIME_OUTPUT_INTDIR}/templight++${CMAKE_EXECUTABLE_SUFFIX}") 55 | add_custom_command(TARGET templight POST_BUILD 56 | COMMAND ${CMAKE_COMMAND} -E ${CLANGXX_LINK_OR_COPY} "${templight_binary}" "${templight_pp}" 57 | WORKING_DIRECTORY "${LLVM_RUNTIME_OUTPUT_INTDIR}") 58 | 59 | set_property(DIRECTORY APPEND 60 | PROPERTY ADDITIONAL_MAKE_CLEAN_FILES ${templight_pp}) 61 | 62 | # Create the templight-cl symlink in the build directory. 63 | set(templight_cl "${LLVM_RUNTIME_OUTPUT_INTDIR}/templight-cl${CMAKE_EXECUTABLE_SUFFIX}") 64 | add_custom_command(TARGET templight POST_BUILD 65 | COMMAND ${CMAKE_COMMAND} -E ${CLANGXX_LINK_OR_COPY} "${templight_binary}" "${templight_cl}" 66 | WORKING_DIRECTORY "${LLVM_RUNTIME_OUTPUT_INTDIR}") 67 | 68 | set_property(DIRECTORY APPEND 69 | PROPERTY ADDITIONAL_MAKE_CLEAN_FILES ${templight_cl}) 70 | 71 | install(TARGETS templight 72 | RUNTIME DESTINATION bin) 73 | 74 | # Create the templight-cl symlinks at installation time. 75 | install(SCRIPT templight_symlink.cmake -DCMAKE_INSTALL_PREFIX=\"${CMAKE_INSTALL_PREFIX}\") 76 | 77 | # Configure plist creation for OS X. 78 | set (TOOL_INFO_PLIST "Info.plist" CACHE STRING "Plist name") 79 | if (APPLE) 80 | if (CLANG_VENDOR) 81 | set(TOOL_INFO_NAME "${CLANG_VENDOR} templight") 82 | else() 83 | set(TOOL_INFO_NAME "templight") 84 | endif() 85 | 86 | set(TOOL_INFO_UTI "${CLANG_VENDOR_UTI}") 87 | set(TOOL_INFO_VERSION "${CLANG_VERSION}") 88 | if (LLVM_SUBMIT_VERSION) 89 | set(TOOL_INFO_BUILD_VERSION 90 | "${LLVM_SUBMIT_VERSION}.${LLVM_SUBMIT_SUBVERSION}") 91 | endif() 92 | 93 | set(TOOL_INFO_PLIST_OUT "${CMAKE_CURRENT_BINARY_DIR}/${TOOL_INFO_PLIST}") 94 | target_link_libraries(templight 95 | PRIVATE 96 | "-Wl,-sectcreate,__TEXT,__info_plist,${TOOL_INFO_PLIST_OUT}") 97 | configure_file("${TOOL_INFO_PLIST}.in" "${TOOL_INFO_PLIST_OUT}" @ONLY) 98 | 99 | set(TOOL_INFO_UTI) 100 | set(TOOL_INFO_NAME) 101 | set(TOOL_INFO_VERSION) 102 | set(TOOL_INFO_BUILD_VERSION) 103 | endif() 104 | 105 | if(CLANG_ORDER_FILE) 106 | target_link_libraries(templight PRIVATE "-Wl,-order_file,${CLANG_ORDER_FILE}") 107 | endif() 108 | 109 | if(WITH_POLLY AND LINK_POLLY_INTO_TOOLS) 110 | target_link_libraries(templight PRIVATE Polly) 111 | if(POLLY_LINK_LIBS) 112 | foreach(lib ${POLLY_LINK_LIBS}) 113 | target_link_libraries(templight PRIVATE ${lib}) 114 | endforeach(lib) 115 | endif(POLLY_LINK_LIBS) 116 | endif(WITH_POLLY AND LINK_POLLY_INTO_TOOLS) 117 | 118 | set(TEMPLIGHT_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}") 119 | set(TEMPLIGHT_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}") 120 | 121 | if(CLANG_INCLUDE_TESTS) 122 | add_subdirectory(test) 123 | add_subdirectory(unittests) 124 | endif() 125 | -------------------------------------------------------------------------------- /Info.plist.in: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | CFBundleIdentifier 6 | @TOOL_INFO_UTI@ 7 | CFBundleInfoDictionaryVersion 8 | 6.0 9 | CFBundleName 10 | @TOOL_INFO_NAME 11 | CFBundleShortVersionString 12 | @TOOL_INFO_VERSION@ 13 | CFBundleVersion 14 | @TOOL_INFO_BUILD_VERSION@ 15 | CFBundleSignature 16 | ???? 17 | 18 | 19 | -------------------------------------------------------------------------------- /LICENSE.TXT: -------------------------------------------------------------------------------- 1 | ============================================================================== 2 | LLVM Release License 3 | ============================================================================== 4 | University of Illinois/NCSA 5 | Open Source License 6 | 7 | Copyright (c) 2007-2014 University of Illinois at Urbana-Champaign. 8 | All rights reserved. 9 | 10 | Developed by: 11 | 12 | LLVM Team 13 | 14 | University of Illinois at Urbana-Champaign 15 | 16 | http://llvm.org 17 | 18 | Permission is hereby granted, free of charge, to any person obtaining a copy of 19 | this software and associated documentation files (the "Software"), to deal with 20 | the Software without restriction, including without limitation the rights to 21 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 22 | of the Software, and to permit persons to whom the Software is furnished to do 23 | so, subject to the following conditions: 24 | 25 | * Redistributions of source code must retain the above copyright notice, 26 | this list of conditions and the following disclaimers. 27 | 28 | * Redistributions in binary form must reproduce the above copyright notice, 29 | this list of conditions and the following disclaimers in the 30 | documentation and/or other materials provided with the distribution. 31 | 32 | * Neither the names of the LLVM Team, University of Illinois at 33 | Urbana-Champaign, nor the names of its contributors may be used to 34 | endorse or promote products derived from this Software without specific 35 | prior written permission. 36 | 37 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 38 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 39 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 40 | CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 41 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 42 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE 43 | SOFTWARE. 44 | 45 | ============================================================================== 46 | The LLVM software contains code written by third parties. Such software will 47 | have its own individual LICENSE.TXT file in the directory in which it appears. 48 | This file will describe the copyrights, license, and restrictions which apply 49 | to that code. 50 | 51 | The disclaimer of warranty in the University of Illinois Open Source License 52 | applies to all code in the LLVM Distribution, and nothing in any of the 53 | other licenses gives permission to use the names of the LLVM Team or the 54 | University of Illinois to endorse or promote products derived from this 55 | Software. 56 | 57 | The following pieces of software have additional or alternate copyrights, 58 | licenses, and/or restrictions: 59 | 60 | Program Directory 61 | ------- --------- 62 | 63 | 64 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | ##===- tools/templight/Makefile ----------------------------*- Makefile -*-===## 2 | # 3 | # The LLVM Compiler Infrastructure 4 | # 5 | # This file is distributed under the University of Illinois Open Source 6 | # License. See LICENSE.TXT for details. 7 | # 8 | ##===----------------------------------------------------------------------===## 9 | CLANG_LEVEL := ../.. 10 | 11 | TOOLNAME = templight 12 | TOOLALIAS = templight++ 13 | 14 | ifdef CLANG_ORDER_FILE 15 | TOOL_ORDER_FILE := $(CLANG_ORDER_FILE) 16 | endif 17 | 18 | # Include tool version information on OS X. 19 | TOOL_INFO_PLIST := Info.plist 20 | 21 | # Include this here so we can get the configuration of the targets that have 22 | # been configured for construction. We have to do this early so we can set up 23 | # LINK_COMPONENTS before including Makefile.rules 24 | include $(CLANG_LEVEL)/../../Makefile.config 25 | 26 | # Have the option of not supporting plugins. This is important for startup 27 | # performance. 28 | ifeq ($(CLANG_PLUGIN_SUPPORT), 1) 29 | NO_DEAD_STRIP := 1 30 | else 31 | TOOL_NO_EXPORTS := 1 32 | endif 33 | 34 | LINK_COMPONENTS := $(TARGETS_TO_BUILD) asmparser bitreader bitwriter codegen \ 35 | instrumentation ipo irreader linker objcarcopts option \ 36 | profiledata selectiondag 37 | USEDLIBS = clangFrontendTool.a clangFrontend.a clangDriver.a \ 38 | clangSerialization.a clangCodeGen.a clangParse.a clangSema.a \ 39 | clangRewriteFrontend.a clangRewrite.a 40 | 41 | ifeq ($(ENABLE_CLANG_STATIC_ANALYZER),1) 42 | USEDLIBS += clangStaticAnalyzerFrontend.a clangStaticAnalyzerCheckers.a \ 43 | clangStaticAnalyzerCore.a 44 | endif 45 | 46 | ifeq ($(ENABLE_CLANG_ARCMT),1) 47 | USEDLIBS += clangARCMigrate.a 48 | endif 49 | 50 | USEDLIBS += clangAnalysis.a clangEdit.a clangAST.a clangLex.a clangBasic.a 51 | 52 | include $(CLANG_LEVEL)/Makefile 53 | 54 | # Set the tool version information values. 55 | ifeq ($(HOST_OS),Darwin) 56 | ifdef CLANG_VENDOR 57 | TOOL_INFO_NAME := $(CLANG_VENDOR) templight 58 | else 59 | TOOL_INFO_NAME := templight 60 | endif 61 | 62 | ifdef CLANG_VENDOR_UTI 63 | TOOL_INFO_UTI := $(CLANG_VENDOR_UTI) 64 | else 65 | TOOL_INFO_UTI := org.llvm.clang 66 | endif 67 | 68 | TOOL_INFO_VERSION := $(word 3,$(shell grep "CLANG_VERSION " \ 69 | $(PROJ_OBJ_DIR)/$(CLANG_LEVEL)/include/clang/Basic/Version.inc)) 70 | ifdef LLVM_SUBMIT_VERSION 71 | TOOL_INFO_BUILD_VERSION := $(LLVM_SUBMIT_VERSION).$(LLVM_SUBMIT_SUBVERSION) 72 | else 73 | TOOL_INFO_BUILD_VERSION := 74 | endif 75 | endif 76 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Templight 2.0 - Template Instantiation Profiler and Debugger 2 | 3 | Templight is a Clang-based tool to profile the time and memory consumption of template instantiations and to perform interactive debugging sessions to gain introspection into the template instantiation process. 4 | 5 | **Disclaimer**: Templight is still at a very preliminary state. We hope to get as much early adoption and testing as we can get, but be aware that we are still experimenting with the output formats and some of the behaviors. 6 | 7 | ## Table of Contents 8 | 9 | - [Templight Profiler](#templight-profiler) 10 | - [Templight Debugger](#templight-debugger) 11 | - [Getting Started](#getting-started) 12 | - [Getting and Compiling Templight](#getting-and-compiling-templight) 13 | - [Invoking Templight](#invoking-templight) 14 | - [Using the Templight Profiler](#using-the-templight-profiler) 15 | - [Default Output Location](#default-output-location) 16 | - [Using the Templight Debugger](#using-the-templight-debugger) 17 | - [Using Blacklists](#using-blacklists) 18 | - [Inspecting the profiles](#inspecting-the-profiles) 19 | - [Credits](#credits) 20 | 21 | ## Templight Profiler 22 | 23 | The templight profiler is intended to be used as a drop-in substitute for the clang compiler (or one of its variants, like clang-cl) and it performs a full compilation, *honoring all the clang compiler options*, but records a trace (or history) of the template instantiations performed by the compiler for each translation unit. 24 | 25 | The profiler will record a time-stamp when a template instantiation is entered and when it is exited, which is what forms the compilation-time profile of the template instantiations of a translation unit. The total memory consumption can also be recorded at these points, which will skew the time profiles, but provide a profile of the memory consumed by the compiler during the template instantiations. 26 | 27 | The profiler is enabled by the templight option `-profiler`, and it supports the following additional templight options: 28 | 29 | - `-stdout` - Output template instantiation traces to standard output (mainly for piping / redirecting purposes). Warning: you need to make sure the source files compile cleanly, otherwise, the output will be corrupted by warning or error messages. 30 | - `-memory` - Profile the memory usage during template instantiations. 31 | - `-safe-mode` - Output Templight traces without buffering, not to lose them at failure (note: this will distort the timing profiles due to file I/O latency). 32 | - `-ignore-system` - Ignore any template instantiation located in system-includes (-isystem), such as from the STL. 33 | - `-output=` - Write Templight profiling traces to . By default, it outputs to "current_source.cpp.trace.pbf" or "current_source.cpp.memory.trace.pbf" (if `-memory` is used). 34 | - `-blacklist=` - Specify a blacklist file that lists declaration contexts (e.g., namespaces) and identifiers (e.g., `std::basic_string`) as regular expressions to be filtered out of the trace (not appear in the profiler trace files). Every line of the blacklist file should contain either "context" or "identifier", followed by a single space character and then, a valid regular expression. 35 | 36 | ## Templight Debugger 37 | 38 | The templight interactive debugger is also a drop-in substitute for the clang compiler, honoring all its options, but it will interrupt the compilation with a console prompt (stdin). The operations of the templight debugger are modeled after the GDB debugger and essentially works the same, *with most commands being the same*, but instead of stepping through the execution of the code (in GDB), it steps through the instantiation of the templates. 39 | 40 | In short, the templight debugger is to template meta-programming what GDB is to regular code. 41 | 42 | The debugger is enabled by the templight option `-debugger`, and it supports the following additional templight options: 43 | 44 | - `-ignore-system` - Ignore any template instantiation located in system-includes (-isystem), such as from the STL. 45 | - `-blacklist=` - Specify a blacklist file that lists declaration contexts (e.g., namespaces) and identifiers (e.g., `std::basic_string`) as regular expressions to be ignored by the debugger. Every line of the blacklist file should contain either "context" or "identifier", followed by a single space character and then, a valid regular expression. 46 | 47 | **NOTE**: Both the debugger and the profiler **can be used together**. Obviously, if compilation is constantly interrupted by the interactive debugger, the time traces recorded by the profiler will be meaningless. Nevertheless, running the profiler during debugging will have the benefit of recording the history of the template instantiations, for later review, and can also record, with reasonably accuracy, the memory consumption profiles. 48 | 49 | ## Getting Started 50 | 51 | ### Getting and Compiling Templight 52 | 53 | Templight must be compiled from source, alongside the Clang source code. 54 | 55 | 1. [Follow the instructions from LLVM/Clang](http://clang.llvm.org/get_started.html) to get a local copy of the Clang source code. 56 | 57 | 2. Clone the templight repository into the clang directories, as follows: 58 | ```bash 59 | (from top-level folder) 60 | $ cd clang/tools 61 | $ mkdir templight 62 | $ git clone templight 63 | ``` 64 | 65 | 3. Add the `templight` subdirectory to CMake: 66 | ```bash 67 | (from top-level folder) 68 | $ cd clang/tools 69 | $ echo "add_clang_subdirectory(templight)" >> CMakeLists.txt 70 | ``` 71 | 72 | 4. (Re-)Compile LLVM / Clang: (same as the corresponding step in LLVM/Clang instructions) 73 | ```bash 74 | (from top-level folder) 75 | $ mkdir build 76 | $ cd build 77 | $ cmake -DLLVM_ENABLE_PROJECTS=clang ../llvm/ 78 | $ make 79 | ``` 80 | 81 | 5. If successful, there should be a `templight` and a `templight++` executable in the build/bin folder. 82 | 83 | **NOTE**: You do not need to apply the patch `templight_clang_patch.diff` and you can ignore the corresponding 84 | version numbers in `templight_clang_version.txt`. Those are meant for other uses case (testing some hooks within clang). 85 | 86 | 87 | ### Invoking Templight 88 | 89 | Templight is designed to be a drop-in replacement for the clang compiler. This is because in order to correctly profile the compilation, it must run as the compiler would, honoring all compilation options specified by the user. 90 | 91 | Because of this particular situation, the options for templight must be specially marked with `-Xtemplight` to distinguish them from other Clang options. The general usage goes like this: 92 | 93 | ```bash 94 | $ templight++ [[-Xtemplight [templight-option]]|[clang-option]] 95 | ``` 96 | 97 | Or, for the MSVC-compatible version of templight (analoguous to clang-cl) use as follows: 98 | 99 | ```bash 100 | $ templight-cl [[-Xtemplight [templight-option]]|[clang-option]] 101 | (OR) 102 | > templight-cl.exe [[-Xtemplight [templight-option]]|[clang-option]] 103 | ``` 104 | 105 | For example, if we have this simple command-line invocation of clang: 106 | 107 | ```bash 108 | $ clang++ -Wall -c some_source.cpp -o some_source.o 109 | ``` 110 | 111 | The corresponding templight profiler invocation, with options `-memory` and `-ignore-system` would look like this: 112 | 113 | ```bash 114 | $ templight++ -Xtemplight -profiler -Xtemplight -memory -Xtemplight -ignore-system -Wall -c some_source.cpp -o some_source.o 115 | ``` 116 | 117 | Note that the order in which the templight-options appear is not important, and that clang options can be interleaved with templight-options. However, **every single templight-option must be immediately preceeded with `-Xtemplight`**. 118 | 119 | As can be seen from that simple example, one can easily substitude the clang command (e.g., `clang++`) with a compound templight invocation (e.g., `templight++ -Xtemplight -profiler -Xtemplight -memory`) and thus, leave the remainder of the command-line intact. That is how templight can be used as a drop-in replacement for clang in any given project, build script or an IDE's build configuration. 120 | 121 | If you use CMake and Clang with the following common trick: 122 | ```bash 123 | $ export CC=/path/to/llvm/build/bin/clang 124 | $ export CXX=/path/to/llvm/build/bin/clang++ 125 | $ cmake 126 | ``` 127 | Then, templight could be swapped in by the same trick: 128 | ```bash 129 | $ export CC="/path/to/llvm/build/bin/templight -Xtemplight -profiler -Xtemplight -memory" 130 | $ export CXX="/path/to/llvm/build/bin/templight++ -Xtemplight -profiler -Xtemplight -memory" 131 | $ cmake 132 | ``` 133 | But be warned that the **cmake scripts will not fully recognize this compiler**, and therefore, you might have to make small changes in the CMake files to be able to handle it. Up to now, experience with building complete cmake projects with templight has been very successful as cmake essentially recognizes templight as a "Clang" compiler and applies the appropriate configuration. There were, however, a few minor issues found that were easily circumvented on a case-by-case basis, and so, be warned that this might not work perfectly on the first try. If anyone is interested in creating some CMake modules to deal with templight specifically, please contact the maintainer, such modules would be more than welcomed. Also, any feedback on your experience working with templight on a large project would be much appreciated. 134 | 135 | ## Using the Templight Profiler 136 | 137 | The templight profiler is invoked by specifying the templight-option `-profiler`. By default, if no other templight-option is specified, the templight profiler will output only time profiling data and will output to one file per input source file and will append the extension `.trace.pbf` to the output filename (object file output). 138 | 139 | For example, running the following: 140 | ```bash 141 | $ templight++ -Xtemplight -profiler -c some_source.cpp 142 | ``` 143 | will produce a file called `some_source.o.trace.pbf` in the same directory as `some_source.cpp`. 144 | 145 | It is, in general, highly recommended to use the `-ignore-system` option for the profiler (and debugger too) because instantiations from standard or third-party libraries can cause significant noise and dramatically increase the size of the trace files produced. If libraries like the STL or most of Boost libraries are used, it is likely that most of the traces produced relate to those libraries and not to your own. Therefore, it is recommended to use `-isystem` when specifying the include directories for those libraries and then use the `-ignore-system` templight-option when producing the traces. 146 | 147 | *Warning*: Trace files produced by the profiler can be very large, especially in template-heavy code. So, use this tool with caution. It is not recommended to blindly generate templight trace files for all the source files of a particular project (e.g., using templight profiler in place of clang in a CMake build tree). You should first identify specific parts of your project that you suspect (or know) lead to template instantiation problems (e.g., compile-time performance issues, or actual bugs or failures), and then create a small source file that exercises those specific parts and produce a templight trace for that source file. 148 | 149 | ### Default Output Location 150 | 151 | The location and names of the output files for the templight traces needs some explanation, because it might not always be straight-forward. The main problem here is that templight is meant to be used as a drop-in replacement for the compiler (and it actually compiles the code, exactly as the vanilla Clang compiler does it). The problem is that you can invoke a compiler in many different ways. On typical small tests, you would simply invoke the compiler on a single source file and produce either an executable or an object file. In other case, you might invoke it with a list of source files to produce either an executable or a library. And for "real" projects, a build system will generally invoke the compiler for each source file, producing an object file each time, and later invoking the linker separately. 152 | 153 | Templight must find a reasonable place to output its traces in all those cases, and often, specifying an output location with `-output` does not really solve the problem (like this problem: multiple source files, one output location?). The only really straight-forward case is with the `-stdout` option, where the traces are simply printed out to the standard output (presumably to be piped elsewhere). 154 | 155 | **One Source File, One Object File** (without `-output` option): Whenever doing a simple compilation where each source file is turned into a single object file (i.e., when using the `-c` option), then the templight tracer will, by default, *output the traces into files located where the output object files are put* and with the same name, but with the addition of the templight extensions. In other words, for compilation instructions like `-c some/path/first_source.cpp some/other/path/second_source.cpp`, you would get traces files: `some/path/first_source.o.trace.pbf` and `some/other/path/second_source.o.trace.pbf`. Whichever options you specify to change the location or name of the generated object file, templight traces will follow. In other words, the default trace filenames are derived from the final output object-file names. 156 | 157 | **One Source File, One Object File** (with `-output` option): Because the `-output` option cannot deal with multiple files specified, templight will ignore this option in this case. 158 | 159 | **One Source File, (Some Output) File**: If you do any other operation that is like a simple compilation (no linking), such as using the `-S` option to general assembly listings or using the `-ast-dump` option, then the situation is analoguous to when you use the `-c` option (produce object-files). The templight trace file names are simply derived from whatever is the final output file name (e.g., `some_source.s.trace.pbf`). If you invoke templight in a way that does not involve any kind of an output file (such as syntax-only or ast-dump to stdout), then templight falls back to deriving the trace file names from the source file names (e.g., `some_source.cpp.trace.pbf`). 160 | 161 | The overall behavior in the above three cases is designed such that when templight is invoked as part of a compilation driven by a build-system (e.g., cmake, make, etc.), which is often done out-of-source, it will output all its traces wherever the build-system stashes the object-files, which is a safe and clean place to put them (e.g., avoid pollution in source tree, avoid possible file-permission problems (read-only source tree), etc..). It is also easy, through most build-systems to create scripts that will move or copy those traces out of those locations (that might be temporary under some setups) and put them wherever is more convenient. 162 | 163 | **Many Source Files, (Some Output) File**: If you invoke the compilation of several source files to be linked into a single executable or library, then templight will merge all the traces into a single output file, whose name is derived from the executable or library name. If no output name is specified, the compiler puts the executable into `a.out`, and templight will put its traces into `a.trace.pbf`. If you specify an output file via the `-output` option, then the trace will be put into that file. 164 | 165 | ## Using the Templight Debugger 166 | 167 | The templight debugger is invoked by specifying the templight-option `-debugger`. When the debugger is launched, it will interrupt the compilation with a console command prompt, just like GDB. The templight debugger is designed to work in a similar fashion as GDB, with many of the same familiar commands and behavior. 168 | 169 | Here is a quick reference for the available commands: 170 | 171 | `break