// Halide tutorial lesson 3: Inspecting the generated code
// Halide入門第3講：檢查llvm編譯生成的程式碼

// This lesson demonstrates how to inspect what the Halide compiler is producing.
// 本課演示了怎樣檢視Halide編譯器做了些什麼

// On linux, you can compile and run it like so:
// linux作業系統，按如下操作編譯和執行
// g++ lesson_03*.cpp -g -I ../include -L ../bin -lHalide -lpthread -ldl -o lesson_03 -std=c++11
// LD_LIBRARY_PATH=../bin ./lesson_03

// On os x:
// g++ lesson_03*.cpp -g -I ../include -L ../bin -lHalide -o lesson_03 -std=c++11
// DYLD_LIBRARY_PATH=../bin ./lesson_03

// If you have the entire Halide source tree, you can also build it by
// running:
//    make tutorial_lesson_03_debugging_1
// in a shell with the current directory at the top of the halide
// source tree.

#include "Halide.h"
#include <stdio.h>

// This time we'll just import the entire Halide namespace
using namespace Halide;

int main(int argc, char **argv) {

    // We'll start by defining the simple single-stage imaging
    // pipeline from lesson 1.

    // This lesson will be about debugging, but unfortunately in C++,
    // objects don't know their own names, which makes it hard for us
    // to understand the generated code. To get around this, you can
    // pass a string to the Func and Var constructors to give them a
    // name for debugging purposes.
    // 本課主要陳述除錯（debugging），但c++中的物件並沒有自己的名字標籤，這就給理解生成程式碼增加了困難
    // 為了克服這個問題，你可以給Func和Var的建構函式傳入一個string型別的名字，從而達到方便除錯的目的
    Func gradient("gradient");
    Var x("x"), y("y");
    gradient(x, y) = x + y;

    // Realize the function to produce an output image. We'll keep it
    // very small for this lesson.
    Buffer<int> output = gradient.realize(8, 8);

    // That line compiled and ran the pipeline. Try running this
    // lesson with the environment variable HL_DEBUG_CODEGEN set to
    // 1. It will print out the various stages of compilation, and a
    // pseudocode representation of the final pipeline.
    // 設定環境變數HL_DEBUG_CODEGEN=1，此時執行程式會打印出編譯的不同階段和最終pipeline的虛擬碼
    // export HL_DEBUG_CODEGEN=1

    // If you set HL_DEBUG_CODEGEN to a higher number, you can see
    // more and more details of how Halide compiles your pipeline.
    // Setting HL_DEBUG_CODEGEN=2 shows the Halide code at each stage
    // of compilation, and also the llvm bitcode we generate at the
    // end.
    // 設定HL_DEBUG_CODEGEN=2，此時會輸出Halide編譯的各個不同階段，而且會輸出llvm
    //（開源編譯器基礎框架）最終生成的位元組碼
    // export HL_DEBUG_CODEGEN=2

    // Halide will also output an HTML version of this output, which
    // supports syntax highlighting and code-folding, so it can be
    // nicer to read for large pipelines. Open gradient.html with your
    // browser after running this tutorial.
    // Halide也提供HTML形式的虛擬碼輸出，支援語法高亮，程式碼摺疊，翻遍大規模複雜pipeline的閱讀
    gradient.compile_to_lowered_stmt("gradient.html", {}, HTML);

    // You can usually figure out what code Halide is generating using
    // this pseudocode. In the next lesson we'll see how to snoop on
    // Halide at runtime.

    printf("Success!\n");
    return 0;
}

1. 設定環境變數HL_DEBUG_CODEGEN=1/2，jit即時編譯打印出中間編譯結果，方便除錯
2. Func.compile_to_lowered_stmt("gradient.html", {}, HTML)， 將Halide中間排程以html形式儲存出來，方便閱讀和理解中間排程過程