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