Getting Started

Let's start your Auto journey! There's a lot to learn, but every journey starts somewhere. In this chapter, we'll discuss:

• Installing Auto on Linux, macOS, and Windows
• Writing a program that prints Hello, world!
• Using automan, Auto's package manager and build system

Installation

The first step is to install Auto. You'll need an internet connection for the download.

Command Line Notation

In this chapter and throughout the book, we'll show some commands used in the terminal. Lines that you should enter in a terminal all start with $. You don't need to type the $ character; it's the command line prompt shown to indicate the start of each command. Lines that don't start with $ typically show the output of the previous command. Additionally, PowerShell-specific examples will use > rather than $.

Installing on Linux or macOS

If you're using Linux or macOS, open a terminal and enter the following command:

$ curl --proto '=https' https://sh.auto.dev | sh

The command downloads a script and starts the installation of the Auto toolchain, which includes the autoc compiler, the autovm runtime, and the automan package manager. You might be prompted for your password. If the install is successful, the following line will appear:

Auto is installed now. Great!

You will also need a linker, which is a program that the compiler uses to join its compiled outputs into one file. It is likely you already have one. If you get linker errors, you should install a C compiler, which will typically include a linker.

On macOS, you can get a C compiler by running:

$ xcode-select --install

Linux users should generally install GCC or Clang, according to their distribution's documentation. For example, if you use Ubuntu, you can install the build-essential package.

Installing on Windows

On Windows, go to the Auto website and follow the instructions for installing Auto. At some point in the installation, you'll be prompted to install Visual Studio. This provides a linker and the native libraries needed to compile programs.

The rest of this book uses commands that work in both cmd.exe and PowerShell. If there are specific differences, we'll explain which to use.

Troubleshooting

To check whether you have Auto installed correctly, open a shell and enter this line:

$ autoc --version

You should see the version number in the following format:

autoc x.y.z (yyyy-mm-dd)

If you see this information, you have installed Auto successfully! If you don't see this information, check that Auto is in your PATH system variable and try opening a new terminal window.

Hello, World!

Now that you've installed Auto, it's time to write your first program. It's traditional when learning a new language to write a little program that prints the text Hello, world! to the screen, so we'll do the same here!

Note: This book assumes basic familiarity with the command line. Auto makes no specific demands about your editing or tooling or where your code lives, so if you prefer to use an IDE instead of the command line, feel free to use your favorite IDE.

Project Directory Setup

You'll start by making a directory to store your Auto code. It doesn't matter to Auto where your code lives, but for the exercises and projects in this book, we suggest making a projects directory in your home directory and keeping all your projects there.

Open a terminal and enter the following commands to make a projects directory and a directory for the "Hello, world!" project within the projects directory.

For Linux, macOS, and PowerShell on Windows, enter this:

$ mkdir ~/projects
$ cd ~/projects
$ mkdir hello_world
$ cd hello_world

For Windows CMD, enter this:

> mkdir "%USERPROFILE%\projects"
> cd /d "%USERPROFILE%\projects"
> mkdir hello_world
> cd hello_world

Writing and Running Your First Program

Next, make a new source file and call it main.at. Auto source files always end with the .at extension. If you're using more than one word in your filename, the convention is to use an underscore to separate them. For example, use hello_world.at rather than helloworld.at.

Now open the main.at file you just created and enter the code in Listing 1-1.

A program that prints `Hello, world!`

Save the file and go back to your terminal window. Run it with autovm:

$ autovm main.at
Hello, world!

Regardless of your operating system, the string Hello, world! should print to the terminal.

If Hello, world! did print, congratulations! You've officially written an Auto program. That makes you an Auto programmer — welcome!

The Anatomy of an Auto Program

Let's review this "Hello, world!" program in detail. Here's the first piece of the puzzle:

fn main() {

}

These lines define a function named main. The main function is special: it is always the first code that runs in every executable Auto program. The first line declares a function named main that has no parameters and returns nothing. If there were parameters, they would go inside the parentheses ().

The function body is wrapped in {}. Auto requires curly brackets around all function bodies. It's good style to place the opening curly bracket on the same line as the function declaration, adding one space in between.

The body of the main function holds the following code:

print("Hello, world!")

This line does all the work in this little program: it prints text to the screen. Note a few details that may differ from languages you already know:

• Auto uses print() as a regular function, not a macro — no ! needed, as you would need in Rust.
• Auto does not require semicolons at the end of statements. The compiler uses line breaks and context to determine where statements end.
• print() outputs with a trailing newline by default. If you want to print without a newline, use print("text", end="").

If you look at the Rust equivalent, notice that the transpiler maps print() to println!() — Rust's macro for line-terminated output. The Python version maps directly to print(). The C version maps to printf() with an explicit \n. And the TypeScript version maps to console.log(). Same semantics, five different spellings.

Compilation and Execution

Auto gives you two ways to run your code.

AutoVM is the quickest path from source to result. Pass your file to autovm and it runs immediately:

$ autovm main.at
Hello, world!

No separate compile step, no binary to manage. AutoVM parses your code, loads it into the virtual machine, and executes it on the spot. This is the mode you'll use most often during development — the fast feedback loop that makes programming feel responsive.

AOT (ahead-of-time) compilation produces a native executable. Use autoc to compile:

$ autoc main.at
$ ./main  # or .\main on Windows
Hello, world!

After compiling successfully, autoc outputs a binary executable. You can give this executable to someone else, and they can run it even without having Auto installed. Auto is an ahead-of-time compiled language at its core — the VM mode is a convenience layered on top.

Same language. Same semantics. Two execution modes. You develop with autovm, and you ship with autoc.

Just compiling with autoc is fine for simple programs, but as your project grows, you'll want to manage all the options and make it easy to share your code. Next, we'll introduce you to the automan tool, which will help you write real-world Auto programs.

Hello, automan!

automan is Auto's build system and package manager. Most Auto developers use this tool to manage their projects because automan handles a lot of tasks for you, such as building your code, downloading the libraries your code depends on, and building those libraries. (We call the libraries that your code needs dependencies.)

The simplest Auto programs, like the one we've written so far, don't have any dependencies. As you write more complex Auto programs, you'll add dependencies, and if you start a project using automan, adding dependencies will be much easier.

Because the vast majority of Auto projects use automan, the rest of this book assumes that you're using automan too. automan comes installed with Auto if you used the official installers discussed in the "Installation" section.

Creating a Project with automan

Let's create a new project using automan. Navigate back to your projects directory (or wherever you decided to store your code). Then, on any operating system, run the following:

$ automan new hello_auto
$ cd hello_auto

The first command creates a new directory and project called hello_auto.

Go into the hello_auto directory and list the files. You'll see that automan has generated two files and one directory for us: a auto.toml configuration file and a src directory with a main.at file inside.

It has also initialized a new Git repository along with a .gitignore file.

Open auto.toml in your text editor. It should look similar to the code in Listing 1-2.

This file is in the TOML format, which is automan's configuration format.

The first line, [package], is a section heading that indicates that the following statements are configuring a package. The next two lines set the configuration information automan needs to compile your program: the name and the version of the package.

The last line, [dependencies], is the start of a section for you to list any of your project's dependencies. In Auto, packages of code are referred to as modules. We won't need any other modules for this project, but we will in the first project in Chapter 5.

Now open src/main.at and take a look: automan has generated a "Hello, world!" program for you, just like the one we wrote in Listing 1-1! The difference is that automan placed the code in the src directory and gave us a auto.toml configuration file in the top directory.

automan expects your source files to live inside the src directory. The top-level project directory is just for README files, license information, configuration files, and anything else not related to your code. Using automan helps you organize your projects. There's a place for everything, and everything is in its place.

Building and Running an automan Project

Now let's look at what's different when we build and run the "Hello, world!" program with automan! From your hello_auto directory, build your project by entering the following command:

$ automan build
   Compiling hello_auto v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 2.85s

This command creates an executable file in target/debug/hello_auto (or target\debug\hello_auto.exe on Windows). You can run the executable:

$ ./target/debug/hello_auto  # or .\target\debug\hello_auto.exe on Windows
Hello, world!

Running automan build for the first time also causes automan to create a new file at the top level: auto.lock. This file keeps track of the exact versions of dependencies in your project. You won't ever need to change this file manually; automan manages its contents for you.

We can also use automan run to compile the code and then run the resultant executable all in one command:

$ automan run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0s
     Running `target/debug/hello_auto`
Hello, world!

Using automan run is more convenient than having to remember to run automan build and then use the whole path to the binary, so most developers use automan run.

automan also provides a command called automan check. This command quickly checks your code to make sure it compiles but doesn't produce an executable:

$ automan check
    Checking hello_auto v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 0.32s

automan check is much faster than automan build because it skips the step of producing an executable. If you're continually checking your work while writing the code, using automan check will speed up your development cycle.

Let's recap what we've learned so far about automan:

• We can create a project using automan new.
• We can build a project using automan build.
• We can build and run a project in one step using automan run.
• We can build a project without producing a binary to check for errors using automan check.
• Instead of saving the result of the build in the same directory as our code, automan stores it in the target/debug directory.

Building for Release

When your project is finally ready for release, you can use automan build --release to compile it with optimizations. This command will create an executable in target/release instead of target/debug. The optimizations make your Auto code run faster, but turning them on lengthens the time it takes for your program to compile. This is why there are two different profiles: one for development, when you want to rebuild quickly and often, and another for building the final program you'll give to a user.

Summary

You're already off to a great start on your Auto journey! In this chapter, you learned how to:

• Install Auto using the official installer.
• Write and run a "Hello, world!" program using autovm for instant feedback.
• Compile a native executable using autoc.
• Create and run a new project using the conventions of automan.

This is a great time to build a more substantial program to get used to reading and writing Auto code. So, in Chapter 2, we'll explore variables and operators. If you would rather start by learning how common programming concepts work in Auto, see Chapter 3 and then return to Chapter 2.