# Build Instructions

The underlying build system for victor is currently `CMake`.  The appropriate version of CMake and other dependencies required for building victor will be fetched automatically.

Configure your shell for command-line builds. This will ensure that you are using the correct Vicos build environment and also add some helper functions for navigation and grepping.

```
source project/victor/envsetup.sh

# for the list of helper commands:
victorhelp
```

To build for vicos (the default):

```
./project/victor/build-victor.sh

# you can also explicitly pass the platform
./project/victor/build-victor.sh -p vicos
```

To build for mac:

```
./project/victor/build-victor.sh -p mac

# To generate a `cozmo.xcodeproj` Xcode project without building
./project/victor/build-victor.sh -p mac -g Xcode -C
```

Note that `ninja` is preferred over Xcode because it is faster. The Xcode project generated by cmake is currently not organized well, but can be used for debugging or performance tooling. When using the Xcode generator, builds invoked through the IDE and command line script are identical.

We use a helper script to generate file lists to tell CMake what to build. Sometimes, when changing branches, CMake doesn't notice that it needs to regenerate build files. You can force it do to so by passing the `-f` flag:

```
./project/victor/build-victor.sh -f
```

By default, the build system generates `Debug` builds. To build `Release` binaries:

```
./project/victor/build-victor.sh -c Release
```

For the complete list of build options:

```
./project/victor/build-victor.sh -h
```

### Build Targets

By default, the build script builds all targets.  To build a specific target, we can pass the `--target` param to `cmake` via the build script:

```
# build animation process
./project/victor/build-victor.sh -- --target vic-anim
```

Listing targets is difficult.  Either of these commands will give you a list of all targets, many of which are intermediates, but you should be able sort through these to get a sense of what to build:

```
# list targets through cmake
./project/victor/build-victor.sh -- --target help

# list targets through ninja
./project/victor/build-victor.sh -- -- -t targets all
```

### Where is the clean option?

CMake creates a `clean` target that removes intermediate artifacts buts leaves the final libs and binaries in place. Running this will cause all targets to rebuild.

```
./project/victor/build-victor.sh -- --target clean
```

Alternatively, since we run out-of-source builds, all output is in `_build`, along with some configuration files in `generated`.  To remove all build artifacts, just delete those two directories:

```
rm -rf _build generated
```

If you are aware of build output that is being placed somewhere in the source tree instead of under `_build` or `generated`, then please file a bug.

### Artifacts

Output from the pre-cmake configuration and generated source files live under `generated/`.
All other build output lives under `_build/`.

#### `generated`

`generated/cmake` contains `.lst` files that are lists of source files corresponding to each cmake target that depends on target defined in a `BUILD.in` file.

`generated/clad` contains source files generated by clad emitters during the cmake build process.

#### `_build`

cmake is configured to output all binaries under `bin/` and all libraries under `lib/`.  Assets are copied/processed and ultimately placed under the `assets/` folder.