Getting Started with T

Welcome to T! This guide will help you install T, create your first project, and understand the basic layout of a T workspace.

Prerequisites

T requires the Nix package manager with flakes enabled. Nix ensures that your T environment is perfectly reproducible across Linux and macOS.

We strongly recommend installing Nix using the Determinate Systems Nix Installer. For detailed, platform-specific steps, please see our:

👉 Nix Installation Guide

Running T

As a user, you don’t need to clone the repository or build the compiler from source! You can run the T shell directly from GitHub using Nix:

nix shell github:b-rodrigues/tlang

This command will download the T executable, fetch all required dependencies, and drop you into a temporary shell where the t command is available, for as long as you stay in that shell.

Starting a New Workspace

T provides a built-in scaffolding tool to initialize your workspaces. There are two types of workspaces in T: - Projects: Designed for data analysis, scripts, and reproducible pipelines. - Packages: Designed for creating reusable functions and libraries to share with others.

Creating a Project

To start a new data analysis project, navigate to your desired folder and run (while in the temporary shell you dropped in before):

t init --project my_analysis

The scaffolding tool will generate a reproducible workspace with the following layout:

my_analysis/
├── tproject.toml       # Project configuration and dependencies
├── flake.nix           # Reproducible environment definition
├── README.md           # Project overview
├── src/
│   └── pipeline.t      # Your main analysis script
├── data/               # Place your raw data files here
├── outputs/            # Output directory for results
└── tests/              # Unit tests for your analysis

Creating a Package

If you want to create a reusable library of T functions, initialize a package instead:

t init --package my_package

The tree layout for a package is structured for development and testing:

my_package/
├── DESCRIPTION.toml    # Package metadata (name, version, exports)
├── flake.nix           # Reproducible environment definition
├── README.md           # Package overview
├── src/
│   └── main.t          # Package source code
├── tests/
│   └── test-my_package.t  # Unit tests for your package
├── examples/           # Usage examples
└── docs/               # Documentation

Running Your Code

Now that you’ve bootstrapped your project or package, you can leave the temporary Nix shell using exit. Move into the project’s directory (if not there already), and type nix develop to drop into the development environment of the project. You may be prompted to make the flake.nix discoverable, you can copy and paste the suggested command or simply run git add . to stage the whole project. Try nix develop again to drop into the development environment. You should see the following:

==================================================
T Project: start_t
==================================================

Available commands:
  t repl              - Start T REPL
  t run <file>        - Run a T file
  t test              - Run tests

To add dependencies:
  * Add them to tproject.toml
  * Run 't update' to sync flake.nix

Inside your project or package directory, you can start the interactive REPL to explore your data:

t repl

(or simply t).

To execute a script from end-to-end, use:

t run scripts/main.t

Next Steps

Now that you have your first project set up and understand the folder structure, you are ready to explore the language features and build reproducible data pipelines!

1. Configure Editors — Configure your editor to play well with T.
2. Language Overview — Explore T’s syntax, types, and standard library functions.
3. Pipeline Tutorial — Learn how to build reproducible, DAG-based data analysis workflows (the core feature of T).
4. Project Development — Dive deeper into managing your tproject.toml and Nix environments.