github.com/llir/llvm@v0.3.6/HACKING.md (about)

     1  # Hacking of llir/llvm
     2  
     3  The purpose of this file is to describe how to get started working on the `llir/llvm` code base. It is intended for people who want more insight into the inner workings of the `llir/llvm`, and who may want to contribute to the project, or change the inner workings to suit their own specific needs.
     4  
     5  ## Installation
     6  
     7  Step one is to install the required tools and dependencies of the project.
     8  
     9  ### llir/ll
    10  
    11  These steps describe how to install the tools required to generate the [llir/ll](https://github.com/llir/ll) LLVM IR parser from an [EBNF grammar](https://github.com/llir/grammar/blob/master/ll.tm).
    12  
    13  ```bash
    14  # Clone repo and submodules.
    15  git clone --recursive https://github.com/llir/ll
    16  
    17  # Install textmapper.
    18  cd ll/tools/textmapper/tm-tool
    19  ./gen.sh
    20  
    21  # Generate LLVM IR parser.
    22  cd ../../..
    23  make
    24  ```
    25  
    26  ### llir/llvm
    27  
    28  These steps describe how to install the [llir/llvm](https://github.com/llir/llvm) LLVM IR library and how to download the associated test data.
    29  
    30  ```bash
    31  # Clone repo and submodules.
    32  git clone --recursive https://github.com/llir/llvm
    33  cd llvm
    34  
    35  # Re-generate asm/enum package when making changes to ir/enum.
    36  make -C asm/enum
    37  
    38  # Build.
    39  go install ./...
    40  
    41  # Run tests.
    42  go test ./...
    43  ```
    44  
    45  ## Directory structure
    46  
    47  This section will give a brief introduction to what each directory contains, so that you may know what parts of the code to look closer at or modify.
    48  
    49  * `asm`: package responsible for parsing LLVM IR assembly into the data structures defined in `llir/llvm/ir`. This package uses the `llir/llvm/ll` parser under the hood, and is mainly responsible for translating the [Textmapper](https://github.com/inspirer/textmapper) generated AST data types into equivalent IR data types. For instance, it performs type resolution (with support for recursive type definitions), identifier resolution (e.g. the occurrences of an identifier `@foo` are mapped to their associated global value [*ir.Global](https://pkg.go.dev/github.com/llir/llvm/ir#Global)), etc.
    50     - `asm/enum`: simple Go package containing enumerated definitions. This package mirrors the definitions of `ir/enum` and is automatically generated (see the associated [Makefile](https://github.com/llir/llvm/blob/master/asm/enum/Makefile)).
    51  * `cmd/l-tm`: simple example tool used to profile CPU and memory usage of the LLVM IR parser. (*Note*, this tool is likely to be removed in future releases of `llir/llvm`.)
    52  * `internal/enc`: internal package dealing with encoding/decoding of LLVM IR identifiers (e.g. global identifier `foo` is encoded as `@foo`). Used by both `llir/llvm/asm` and `llir/llvm/ir`.
    53  * `ir`: top-level LLVM IR package, defines the intermediate representation of modules, functions, global variables and other key concepts of LLVM IR.
    54     - `ir/constant`: implements LLVM IR constants, which act as immutable values.
    55     - `ir/enum`: simple Go package containing enumerated definitions. This package exists mainly to not proliferate the number of definitions in the top-level `llir/llvm/ir` package.
    56     - `ir/metadata`: defines the metadata types of LLVM IR, including DWARF debug information.
    57     - `ir/types`: defines the data types of LLVM IR (e.g. `i32`, `double`, etc).
    58     - `ir/value`: provides a Go interface definition of LLVM IR values, a core concept in the `llir/llvm/ir` API.
    59  * `testdata`: submodule of https://github.com/llir/testdata containing test data from the official LLVM project and from Coreutils and SQLite.