github.com/Benchkram/bob@v0.0.0-20220321080157-7c8f3876e225/README.md (about)

     1  # Bob 
     2  _Inspired by Make and Bazel · Made for humans_
     3  
     4  <p>
     5      <a href="https://github.com/benchkram/bob/releases">
     6          <img src="https://img.shields.io/github/release/benchkram/bob.svg" alt="Latest Release">
     7      </a>
     8      <a href="https://pkg.go.dev/github.com/benchkram/bob?tab=doc">
     9          <img src="https://godoc.org/github.com/golang/gddo?status.svg" alt="GoDoc">
    10      </a>
    11      <a href="https://github.com/benchkram/bob/actions">
    12          <img src="https://github.com/benchkram/bob/actions/workflows/main.yml/badge.svg" alt="Build Status">
    13      </a>
    14  </p>
    15  
    16  
    17  Bob is a build system, a task runner as well as tooling for Git Multi-repos, all bundled into a single binary.
    18  
    19  With bob, you can:
    20  
    21  - **Build** your programs efficiently, as Bob tracks build inputs and caches compiled outputs, providing fast
    22    incremental builds.
    23  - **Run** local development environments, whether they are simple binaries, docker-compose files, or a mix of both.
    24  - **Multi-Repo Tooling** Easily manage multi-repo setups, with bulk Git operations.
    25  
    26  ⚠️⚠️⚠️ _Warning: Bob and its documentation is in a early stage. Most of the
    27  features are fully-functional and tested, but some details are yet to be ironed out._
    28  
    29  ## Install
    30  
    31  ### Release builds
    32  
    33  [Download](https://github.com/benchkram/bob/releases) the latest release from GitHub.
    34  ### Install from Source
    35  
    36  If you already have Go 1.16 or later installed, the short version is:
    37  
    38  ```bash
    39  go install github.com/benchkram/bob@latest
    40  ```
    41  
    42  For shell autocompletion (bash and zsh supported) add `source <(bob completion)` to your `.bashrc`/`.zshrc`.
    43  
    44  ### Build System
    45  
    46  Bobs generates its internal build graph from tasks described in a `bob.yaml` file (we usually refer to it as "bobfile").  
    47  The basic components of a build task are:
    48  
    49  - **input**: Whenever an input changes, the task's commands need to be re-executed [default: *]
    50  - **cmd**: Commands to be executed
    51  - **target**: File(s) or directories that are created when the commands are run and can be reused in other tasks.
    52  
    53  Example of a `bob.yaml` file:
    54  
    55  ```yaml
    56  build:
    57    build:
    58      input: ./main.go
    59      cmd: go build -o ./app
    60      target: ./app
    61  ```
    62  
    63  Multiline `sh` and `bash` commands are entirely possible, and are powered by [mvdan/sh](https://github.com/mvdan/sh).
    64  
    65  Take a look into the [server-db](./example/server-db) example for a step-by-step tutorial.
    66  
    67  ### Local Development
    68  
    69  Our goal is to create a world-class local development experience by integrating seamlessly with the build-system and
    70  enabling you to start right after cloning a repository. Let the build-system create binaries and docker images, then
    71  execute & control them from one terminal using `bob run`. No more back-and-forth tab switching.
    72  
    73  Ideally, those are the only two commands necessary to get started when joining a new project that uses Bob:
    74  
    75  ```bash
    76  git clone
    77  bob run
    78  ```
    79  
    80  #### Web Server Example
    81  
    82  Individual steps for web server development are likely similar to this:
    83  
    84  1. Code generation using an [IDL](https://en.wikipedia.org/wiki/Interface_description_language), like openapi or
    85     protobuf
    86  2. Compile a server binary
    87  3. Run a database in docker
    88  4. Run the server
    89  
    90  Those build/run tasks can be described in a _bob.yaml_ file. This allows `bob run` to launch and give you control to a
    91  local development environment.
    92  
    93  An in-depth example is available [here](./example/server-db).
    94  
    95  ### Multi-repo Git Tooling
    96  
    97  Bob enables a natural feeling git workflow for Git multi-repo setups without relying on Git Submodules.
    98  
    99  To do this, Bob uses the concept of a "workspace" to track other git repositories. Inside a workspace you can use the
   100  usual every day git-operations through bob with visually enhanced output for the multi-repo cases.
   101  
   102  Here is an example of `bob git status` in a workspace:
   103  
   104  <img src="doc/bob-git-status.png" width="50%" />
   105  
   106  Highlighted directories indicate child Git repositories and therefore `bob git add` and `bob git commit` will only
   107  operate on the repository a file belongs to allowing to create repository overlapping commits all together.
   108  
   109  Take a look into the [bob git README](./bobgit/README.md) for the current status.
   110  
   111  #### Setting Up a Workspace
   112  
   113  To set up a new bob workspace you first have to initialize it:
   114  
   115  ```bash
   116  bob workspace init
   117  ```
   118  
   119  This creates a _.bob.workspace_ file and initializes a new git repository in the current directory.
   120  
   121  Adding repositories to the workspace:
   122  
   123  ```bash
   124  bob workspace add git@github.com:benchkram/bob.git
   125  bob clone # calls git clone for missing repos
   126  ```
   127  
   128  Cloning an existing workspace from a remote git repository:
   129  
   130  ```bash
   131  bob clone git@github.com:benchkram/bob.git
   132  ```
   133  
   134  ### Documentation
   135  Full documentation of Bob is available at [bob.build](https://bob.build/docs)
   136  ### Dependencies
   137  
   138  A list of Bob's top dependencies:
   139  
   140  - [charmbracelet/bubbletea](https://github.com/charmbracelet/bubbletea) - Used in Bob's Terminal User Interface
   141  - [docker/compose](https://github.com/docker/compose) - Enables us to run docker-compose files the same way
   142    `docker compose` does
   143  - [sh](https://github.com/mvdan/sh) - Parsing/execution of shell commands