> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# manastech/crystal

Common CircleCI tasks for the Crystal programming language.


## Commands

### with-shards-cache

Run a set of steps with shards cache enabled.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache-key` | string | shard.yml | File to use as a shards cache checksum |
| `cache-version` | string | v1 | Cache version; increment this for a fresh cache |
| `include-branch-in-cache-key` | boolean | true | If true, includes current branch name in cache key |
| `dir` | string | ~/.cache/shards | Path to your shards cache |
| `steps` | steps |  | Input any custom steps to run with your shards cache |

### shards-install

Install Shards dependencies.


### spec

Run crystal spec with given spec options.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `spec-options` | string |  | Additional options to crystal spec like --tag fast |
| `junit` | boolean | true | Store crystal spec output in JUnit format and use it as CircleCI test results |
| `junit-output` | string | ~/test-results/crystal-spec | JUnit output location |

### format-check

Check the format of the source code.


### version

Show Crystal and Shards version.


## Jobs

### test

Download dependencies, run specs and check format with specified Crystal version.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `spec-options` | string |  | Additional options to crystal spec like --tag fast |
| `junit` | boolean | true | Store crystal spec output in JUnit format and use it as CircleCI test results |
| `junit-output` | string | ~/test-results/crystal-spec | JUnit output location |
| `format-check` | boolean | true | Check the format of the source code |
| `executor` | executor | default | The executor to use for this job |
| `cache-key` | string | shard.yml | File to use as a shards cache checksum |
| `cache-version` | string | v1 | Cache version; increment this for a fresh cache |
| `include-branch-in-cache-key` | boolean | true | If true, includes current branch name in cache key |

## Executors

### default

Use the official Crystal Docker image as executor.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | latest | crystallang/crystal Docker image tag. Valid values: latest, nightly or M.m.p.
See https://hub.docker.com/r/crystallang/crystal/
 |

## Examples

### latest

Example for testing using latest Crystal release.


```yaml
workflows:
  version: 2
  build:
    jobs:
      - crystal/test
orbs:
  crystal: manastech/crystal@x.y
version: 2.1
```

### nightly

Example for testing using nightly Crystal release.


```yaml
workflows:
  version: 2
  build:
    jobs:
      - crystal/test:
          name: test-on-nightly
          executor:
            name: crystal/default
            tag: nightly
orbs:
  crystal: manastech/crystal@x.y
version: 2.1
```

### binary-dependencies

Adding binary dependencies via apt.


```yaml
workflows:
  version: 2
  build:
    jobs:
      - crystal/test:
          pre-steps:
            - run: apt-get update && apt-get install -y libsqlite3-dev
orbs:
  crystal: manastech/crystal@x.y
version: 2.1
```

### external-services

Use docker to add external services. Define a custom executor but keep using the crystal/test job.


```yaml
executors:
  crystal_mysql:
    docker:
      - image: crystallang/crystal:latest
        environment:
          DATABASE_URL: mysql://root@localhost/db
      - image: mysql:5.7
        environment:
          MYSQL_DATABASE: db
          MYSQL_ALLOW_EMPTY_PASSWORD: 'yes'
workflows:
  version: 2
  build:
    jobs:
      - crystal/test:
          executor: crystal_mysql
          pre-steps:
            - run:
                name: Waiting for service to start (check dockerize)
                command: sleep 5
orbs:
  crystal: manastech/crystal@x.y
version: 2.1
```