Getting Started

The first step to getting started with Nim is installing the compiler. Once that's done, we'll look at writing your first classic "Hello World" program. Finally, we will look at Nimble, Nim's package manager.

Installing Nim

In order to start writing programs in Nim, you need to first install the Nim compiler. The way that you install Nim depends upon your computer's Operating System (OS) and is subject to changing before Nim's 1.0 release.

Steps are included below for installing on Windows, Mac and Linux though other Unix like operating systems. These steps involve downloading files from the internet, so it's best to first make sure you have a working internet connection.

Installation on Windows

The Nim developers provide pre-built binaries of the most recent Nim release for both 32-bit (x32) and 64-bit (x64) versions of Windows. These installer binaries include the Aporia IDE for Nim development and the Mingw-w64 C compiler which is the recommended C compiler on Windows platforms. They also includes the Nimble executable, which should be selected for installation if you wish to use Nimble. These pre-built binaries can always be found at the main Nim download page.

Installation on Mac OS X, Linux and other Unix based systems

Pre-built binaries are no currently provided for platforms other than Windows. The recommended installation method to install Nim on mac OS X, Linux and other Unix like platforms is to download the generated C source code and compile it.

This requires a working C compiler - CLang for Mac OS X or GCC for Linux and any other Unix based system, so make sure you have a working C toolchain first.

The first step is to download and extract the snapshot archive. This can be downloaded from the Nim download page. Save the archive file somewhere, then extract it to wherever you want to install Nim (I would recommend ~/programs/nim and this path will be used from now on - if you choose another install location, be sure to substitute this path for your chosen install location).
Open a terminal and change the working directory to where you extracted the archive downloaded in the first step:

$ cd ~/programs/nim
Build the Nim executable:

$ sh build.sh
Add the bin directory to your PATH environment variable. Adding an item to your path depends on your shell.
Restart your terminal to reload the PATH variable, then test that you can use the Nim compiler:
```
$ nim -v
```
This should output the version of Nim that you just installed, and should look similar to the below:
```
Nim Compiler Version 0.14.2 (2016-06-09)
Copyright (c) 2006-2016 by Andreas Rumpf

git hash: 10fdd241ea1d987f12820b6c5467e21dc08d1c23
active boot switches: -d:release
```

Writing your first "Hello World" program

As you now have Nim installed, the first thing to do is to make sure the compiler is working as expected. Traditionally, we do this by writing a simple program that writes "Hello World" to the screen.

This is actually extremely easy in Nim. We'll start off by creating a directory for our program, then we'll write the actual code. Here, we'll be creating the program in the directory ~/hello-nim.

$ mkdir ~/hello-nim
$ cd ~/hello-nim
$ touch hello.nim

The above commands will create the directory ~/hello-nim and create a file called hello.nim within it. Note that Nim source files end with the file extension .nim. All of the code for your program will live in this new file, so open it with your favourite text editor and enter the following content:

echo "Hello World"

Now go back to your terminal window and compile the program then run it.

$ nim c -r hello.nim
Hint: used config file '/usr/local/Cellar/nim/0.14.2/nim/config/nim.cfg' [Conf]
Hint: system [Processing]
Hint: hello [Processing]
CC: hello
CC: stdlib_system
Hint:  [Link]
Hint: operation successful (10297 lines compiled; 0.677 sec total; 15.504MiB; Debug Build) [SuccessX]
Hello World

In Windows, change the command ./hello to ./hello.exe. You should see the text Hello World printed out in the terminal. If you did, you've got a working Nim compiler! If not, something went wrong during the installation. Try re-reading this guide and if you get stuck ask on the forums or on IRC.

This hello world example program is included in the examples package distributed with thi book.

Using the Nim compiler

Building and running some code immediately

To build a program and run it at once, you can start nim with a single file:

$ nim c -r some_program.nim

Note the -r flag, this is a short command that is shorthand for --run and tells the compiler to run your executable as soon as it is finished building.

Creating an executable

To build an executable from your code, simply call the nim compiler:

$ nim c some_program.nim

Note: By default, Nim programs are not fully optimized and include safety checks and debugging features that slow execution down slightly. Before deploying a program, be sure to build an optimized release build:

$ nim c -d:release some_program.nim

Other compiler options

The Nim compiler has a lot of other options that can be passed to it, such as to customize whether certain checks are turned on or not. More information about using the Nim compiler can be sen in the official Nim Compiler User Guide , or by passing the -h flag to the compiler:

$ nim -h
Nim Compiler Version 0.14.2 (2016-06-11) [MacOSX: amd64]
Copyright (c) 2006-2016 by Andreas Rumpf
::

    nim command [options] [projectfile] [arguments]

Command:
  compile, c                compile project with default code generator (C)
  doc                       generate the documentation for inputfile
  doc2                      generate the documentation for the whole project

Arguments:
  arguments are passed to the program being run (if --run option is selected)
Options:
  -p, --path:PATH           add path to search paths
...