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

# circleci/build-tools

An orb with some general-purpose tools to help analyze, debug, and optimize your CircleCI builds.


## Commands

### ensure-command

Given a command name, make sure it exists in the runtime, abort the job if it does not.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `command` | string |  | The name of the command that needs to exist. |

### env-info

Save information about the job enviroment, to be stored as artifacts and inspected later


| Parameter | Type | Default | Description |
|---|---|---|---|
| `data-dir` | string | ~/.ccidiag/env-info | Directory in which to output job environment information (will be created if necessary)
 |

### init-file

Given a file path, make sure the directories and the file exist; create them if they don't


| Parameter | Type | Default | Description |
|---|---|---|---|
| `file` | string |  | Path to the file you want to ensure exists |

### install-ci-tools

Install packages commonly required in CircleCI jobs; designed to replicate the tooling pre-loaded in CircleCI's Docker convenience images: https://github.com/circleci/circleci-images/blob/master/shared/images/Dockerfile-basic.template#L26


### ios-logs

Save Fastlane logs, Xcode information and iOS simulator crash reports from an iOS job, to be stored as artifacts and inspected later


| Parameter | Type | Default | Description |
|---|---|---|---|
| `data-dir` | string | ~/.ccidiag/ios-logs | Directory in which to output job environment information (will be created if necessary)
 |

### memory

Save memory usage information, to be stored as artifacts and inspected later


| Parameter | Type | Default | Description |
|---|---|---|---|
| `data-dir` | string | ~/.ccidiag/memory | Directory in which to output memory usage information (will be created if necessary)
 |

### merge-with-parent

Merge the current branch with the parent branch to test for conflicts or unexpected behaviour before actually merging.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `named_detached_parent` | string |  | Name used for a branch created on checkout when a detached HEAD state is expected. This way the merge target has a name you can reference.
 |
| `no_commit` | boolean | false | Don't commit the merged state. Can see the changes with `git diff`.
 |
| `no_fast_forward` | boolean | false | Do not allow merge by fast-forwarding the commits. Forces the changes to be staged for a commit.
 |
| `parent` | string |  | Strictly set a parent (e.g "main") that the branch being tested should always be merged in to. The parent branch will attempt to be discovered if this is blank.
 |

### run-filtered

Conditionally run a step, or a series of steps, via paramaterized branch and/or tag filters. Provide either exact branch/tag names or regular expressions. This command *must* be run as the last command in a job (given that you may pass multiple steps to it via the `steps` parameter, however, it is fairly adaptable): if commands or steps are placed after this command within a particular job in your config.yml, they *will not* run. Designed to mirror job-level branch/tag filters: https://circleci.com/docs/2.0/workflows/#using-regular-expressions-to-filter-tags-and-branches


| Parameter | Type | Default | Description |
|---|---|---|---|
| `ignore-branch` | string | // | Exact name or regular expression specifying branch(es) to ignore. Defaults to a regular expression ignoring no branches, following the default execution pattern for job-level branch filtering: https://circleci.com/docs/2.0/workflows/#branch-level-job-execution
 |
| `ignore-tag` | string | /.*/ | Exact name or regular expression specifying tag(s) to ignore. Defaults to a regular expression ignoring all tags, following the default execution pattern for job-level tag filtering: https://circleci.com/docs/2.0/workflows/#executing-workflows-for-a-git-tag
 |
| `only-branch` | string | /.*/ | Exact name or regular expression specifying branch(es) to accept. Defaults to a regular expression accepting all branches, following the default execution pattern for job-level branch filtering: https://circleci.com/docs/2.0/workflows/#branch-level-job-execution
 |
| `only-tag` | string | // | Exact name or regular expression specifying tag(s) to accept. Defaults to a regular expression accepting no tags, following the default execution pattern for job-level tag filtering: https://circleci.com/docs/2.0/workflows/#executing-workflows-for-a-git-tag
 |
| `steps` | steps |  | Steps that you'd like to run, if your provided conditions are met
 |

### script-run

Given a string (can be multi-line), write that string to a file, make it executable, and run it.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `file-directory` | string | ~/.circleci/orbs/script-run/ |  |
| `file-name` | string | script-run-persisted |  |
| `label` | string | Run the script (in the `script-run` command in build-tools) | Name for the step in which your script will be run
 |
| `output-file` | string |  | When present, save the output to a file at the path given. otherwise, output directly. |
| `script` | string |  | A string containing your entire script. If you want to make this inline we recommend using the `|` operator in YAML to create a multi-line string.
 |

### store-report

Store diagnostic data as artifacts. Use after running the other diagnostic commands.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `data-dir` | string | ~/.ccidiag | Directory to store as artifacts (should conform with the value passed to this parameter in the other diagnostic commands)
 |

### test-results

Generate sample JUNIT XML, for help in debugging Test Summary issues


| Parameter | Type | Default | Description |
|---|---|---|---|
| `data-dir` | string | ~/.ccidiag/test-results | Directory in which to output sample test results (will be created if necessary)
 |
| `upload` | boolean | true | Should these sample test results be stored, so they display in Test Summary?
 |

## Jobs

### introspect-orbs

A job that outputs information about all the orbs used in the build in which the job is invoked.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `checkout` | boolean | true | Boolean for whether to run a `checkout` first; default is true
 |
| `config-path` | string | .circleci/config.yml |  |
| `working-file` | string | ~/.circleci/orb-introspection.yml |  |

## Executors

### bash

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | latest |  |

### default

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | stable |  |

### macos

| Parameter | Type | Default | Description |
|---|---|---|---|
| `xcode-version` | string | 13.0.0 | Version of Xcode to use. See the following for full list of options: https://circleci.com/docs/2.0/testing-ios/#supported-xcode-versions
 |

### python

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | 3.9.1 |  |

### ruby

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | 2.7.1 |  |

## Examples

### ci-tools

Use a third-party Docker image and layer on CircleCI's convenience image tooling at job runtime


```yaml
jobs:
  your-job:
    docker:
      - image: your-third/party-image:image-tag
    steps:
      - checkout
      - build-tools/install-ci-tools
      - jq/install
      - docker/install-docker-tools
      - browser-tools/install-browser-tools
orbs:
  browser-tools: circleci/browser-tools@x.y.z
  build-tools: circleci/build-tools@x.y.z
  docker: circleci/docker@x.y.z
  jq: circleci/jq@x.y.z
version: 2.1
workflows:
  your-workflow:
    jobs:
      - your-job
```

### debug-ios-job

Use the orb's ios-logs and store-report commands to store iOS diagnostic info for debugging


```yaml
executors:
  macos:
    macos:
      xcode: 10.1.0
jobs:
  build:
    executor: macos
    steps:
      - checkout
  deploy:
    executor: macos
    steps:
      - checkout
orbs:
  build-tools: circleci/build-tools@x.y.z
version: 2.1
workflows:
  build-and-deploy:
    jobs:
      - build:
          post-steps:
            - build-tools/ios-logs
            - build-tools/store-report
      - deploy:
          requires:
            - build
```

### full-diagnostic

See how to use this orb's diagnostic commands, with the exception of ios-logs (which has its own example)


```yaml
executors:
  machine:
    machine: true
jobs:
  build:
    executor: machine
    steps:
      - checkout
  deploy:
    executor: machine
    steps:
      - checkout
orbs:
  build-tools: circleci/build-tools@x.y.z
version: 2.1
workflows:
  build-and-deploy:
    jobs:
      - build:
          post-steps:
            - build-tools/store-report
          pre-steps:
            - build-tools/env-info
            - build-tools/memory
            - build-tools/test-results
      - deploy:
          requires:
            - build
```

### merge-with-parent

Simulate a git merge command against a parent repository, either to investigate merge conflicts or run integration testing against the result.


```yaml
jobs:
  test-with-merge:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - build-tools/merge-with-parent
      - ./your-test-script
orbs:
  build-tools: circleci/build-tools@x.y
version: 2.1
workflows:
  your-workflow:
    jobs:
      - test-with-merge
```

### node-debug-custom-param

Use the orb's env-info command, with custom parameters, to debug a Node.js project


```yaml
executors:
  node:
    docker:
      - image: circleci/node
jobs:
  build:
    executor: node
    steps:
      - checkout
  deploy:
    executor: node
    steps:
      - checkout
orbs:
  build-tools: circleci/build-tools@x.y.z
version: 2.1
workflows:
  build-and-deploy:
    jobs:
      - build:
          post-steps:
            - build-tools/env-info:
                data-dir: diagnostic-report/env-info
            - build-tools/store-report:
                data-dir: diagnostic-report
      - deploy:
          requires:
            - build
```