# Your first project

> Create and understand an Alice project with source files, tests, and dependencies.

Canonical: https://alice-lang.org/documentation/learn/first-project/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

## Create and run

```sh
alice new tea-shop
cd tea-shop
alice run
```

`alice new` creates a runnable package. Its important files are:

```text
tea-shop/
  alice.toml        # package and dependencies
  src/main.al       # application source
  test/             # Alice tests
  .gitignore
```

Builds create `bin/`, `obj/`, and `.alice/`. Keep these generated directories out of version control. Commit `alice.toml`, your source, your tests, and the generated `alice.lock`.

## Add a method

Replace `src/main.al` with:

```alice
def total_cents(price : Int32, quantity : Int32) : Int32
  price * quantity
end

puts total_cents(250, 3)
```

`alice run` prints `750`. Keep prices in integer cents when exact amounts are needed. Top-level statements are the application's entry point; methods can also be exercised without running that entry point during tests.

## Add a test

Create `test/total_test.al`:

```alice
def test_total_cents
  assert_equal 750, total_cents(250, 3)
  assert_equal 0, total_cents(250, 0)
end
```

Run the workflow:

```sh
alice test
alice fmt
alice fmt --check
alice build --release
```

`alice test` builds the package and checks the tests against its sources and resolved dependencies. `fmt` updates formatting; `fmt --check` exits unsuccessfully when files need formatting.

## Add a dependency

```sh
alice add Newtonsoft.Json --version '13.*'
alice list
```

The dependency is recorded in `alice.toml`. A restore writes the exact resolved version to `alice.lock`. Use `alice update` when you intend to refresh those resolutions.

The generated `.alice/tea-shop.alproj` connects the package to MSBuild. Edit the manifest, rather than that generated file. Learn the full [manifest format](https://alice-lang.org/documentation/tools/manifest.md), then use [workspaces](https://alice-lang.org/documentation/tools/workspaces.md) when a library and an application need separate packages.

## Continue reading

- Previous: [A tour of Alice](https://alice-lang.org/documentation/learn/tour.md)
- Next: [Coming from Ruby or C#](https://alice-lang.org/documentation/learn/from-ruby.md)