github.com/vanadium-archive/go.jiri@v0.0.0-20160715023856-abfb8b131290/cmd/jiri/cmd.go (about) 1 // Copyright 2015 The Vanadium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // The following enables go generate to generate the doc.go file. 6 //go:generate go run $JIRI_ROOT/release/go/src/v.io/x/lib/cmdline/testdata/gendoc.go -env="" . 7 8 package main 9 10 import ( 11 "runtime" 12 13 "v.io/jiri/tool" 14 "v.io/x/lib/cmdline" 15 ) 16 17 func init() { 18 runtime.GOMAXPROCS(runtime.NumCPU()) 19 20 cmdRoot = newCmdRoot() 21 tool.InitializeRunFlags(&cmdRoot.Flags) 22 } 23 24 func main() { 25 cmdline.Main(cmdRoot) 26 } 27 28 // cmdRoot represents the root of the jiri tool. 29 var cmdRoot *cmdline.Command 30 31 // Use a factory to avoid an initialization loop between between the 32 // Runner functions in subcommands and the ParsedFlags field in the 33 // Command. 34 func newCmdRoot() *cmdline.Command { 35 return &cmdline.Command{ 36 Name: "jiri", 37 Short: "Multi-purpose tool for multi-repo development", 38 Long: ` 39 Command jiri is a multi-purpose tool for multi-repo development. 40 `, 41 LookPath: true, 42 Children: []*cmdline.Command{ 43 cmdCL, 44 cmdImport, 45 cmdProfile, 46 cmdProject, 47 cmdRebuild, 48 cmdSnapshot, 49 cmdUpdate, 50 cmdWhich, 51 }, 52 Topics: []cmdline.Topic{ 53 topicFileSystem, 54 topicManifest, 55 }, 56 } 57 } 58 59 var topicFileSystem = cmdline.Topic{ 60 Name: "filesystem", 61 Short: "Description of jiri file system layout", 62 Long: ` 63 All data managed by the jiri tool is located in the file system under a root 64 directory, colloquially called the jiri root directory. The file system layout 65 looks like this: 66 67 [root] # root directory (name picked by user) 68 [root]/.jiri_root # root metadata directory 69 [root]/.jiri_root/bin # contains tool binaries (jiri, etc.) 70 [root]/.jiri_root/update_history # contains history of update snapshots 71 [root]/.manifest # contains jiri manifests 72 [root]/[project1] # project directory (name picked by user) 73 [root]/[project1]/.jiri # project metadata directory 74 [root]/[project1]/.jiri/metadata.v2 # project metadata file 75 [root]/[project1]/.jiri/<<cls>> # project per-cl metadata directories 76 [root]/[project1]/<<files>> # project files 77 [root]/[project2]... 78 79 The [root] and [projectN] directory names are picked by the user. The <<cls>> 80 are named via jiri cl new, and the <<files>> are named as the user adds files 81 and directories to their project. All other names above have special meaning to 82 the jiri tool, and cannot be changed; you must ensure your path names don't 83 collide with these special names. 84 85 There are two ways to run the jiri tool: 86 87 1) Shim script (recommended approach). This is a shell script that looks for 88 the [root] directory. If the JIRI_ROOT environment variable is set, that is 89 assumed to be the [root] directory. Otherwise the script looks for the 90 .jiri_root directory, starting in the current working directory and walking up 91 the directory chain. The search is terminated successfully when the .jiri_root 92 directory is found; it fails after it reaches the root of the file system. Thus 93 the shim must be invoked from the [root] directory or one of its subdirectories. 94 95 Once the [root] is found, the JIRI_ROOT environment variable is set to its 96 location, and [root]/.jiri_root/bin/jiri is invoked. That file contains the 97 actual jiri binary. 98 99 The point of the shim script is to make it easy to use the jiri tool with 100 multiple [root] directories on your file system. Keep in mind that when "jiri 101 update" is run, the jiri tool itself is automatically updated along with all 102 projects. By using the shim script, you only need to remember to invoke the 103 jiri tool from within the appropriate [root] directory, and the projects and 104 tools under that [root] directory will be updated. 105 106 The shim script is located at [root]/release/go/src/v.io/jiri/scripts/jiri 107 108 2) Direct binary. This is the jiri binary, containing all of the actual jiri 109 tool logic. The binary requires the JIRI_ROOT environment variable to point to 110 the [root] directory. 111 112 Note that if you have multiple [root] directories on your file system, you must 113 remember to run the jiri binary corresponding to the setting of your JIRI_ROOT 114 environment variable. Things may fail if you mix things up, since the jiri 115 binary is updated with each call to "jiri update", and you may encounter version 116 mismatches between the jiri binary and the various metadata files or other 117 logic. This is the reason the shim script is recommended over running the 118 binary directly. 119 120 The jiri binary is located at [root]/.jiri_root/bin/jiri 121 `, 122 } 123 124 var topicManifest = cmdline.Topic{ 125 Name: "manifest", 126 Short: "Description of manifest files", 127 Long: ` 128 Jiri manifest files describe the set of projects that get synced and tools that 129 get built when running "jiri update". 130 131 The first manifest file that jiri reads is in $JIRI_ROOT/.jiri_manifest. This 132 manifest **must** exist for the jiri tool to work. 133 134 Usually the manifest in $JIRI_ROOT/.jiri_manifest will import other manifests 135 from remote repositories via <import> tags, but it can contain its own list of 136 projects and tools as well. 137 138 Manifests have the following XML schema: 139 140 <manifest> 141 <imports> 142 <import remote="https://vanadium.googlesource.com/manifest" 143 manifest="public" 144 name="manifest" 145 /> 146 <localimport file="/path/to/local/manifest"/> 147 ... 148 </imports> 149 <projects> 150 <project name="my-project" 151 path="path/where/project/lives" 152 protocol="git" 153 remote="https://github.com/myorg/foo" 154 revision="ed42c05d8688ab23" 155 remotebranch="my-branch" 156 gerrithost="https://myorg-review.googlesource.com" 157 githooks="path/to/githooks-dir" 158 runhook="path/to/runhook-script" 159 /> 160 ... 161 </projects> 162 <tools> 163 <tool name="jiri" 164 package="v.io/jiri" 165 project="release.go.jiri" 166 /> 167 ... 168 </tools> 169 </manifest> 170 171 The <import> and <localimport> tags can be used to share common projects and 172 tools across multiple manifests. 173 174 A <localimport> tag should be used when the manifest being imported and the 175 importing manifest are both in the same repository, or when neither one is in a 176 repository. The "file" attribute is the path to the manifest file being 177 imported. It can be absolute, or relative to the importing manifest file. 178 179 If the manifest being imported and the importing manifest are in different 180 repositories then an <import> tag must be used, with the following attributes: 181 182 * remote (required) - The remote url of the repository containing the 183 manifest to be imported 184 185 * manifest (required) - The path of the manifest file to be imported, 186 relative to the repository root. 187 188 * name (optional) - The name of the project corresponding to the manifest 189 repository. If your manifest contains a <project> with the same remote as 190 the manifest remote, then the "name" attribute of on the <import> tag should 191 match the "name" attribute on the <project>. Otherwise, jiri will clone the 192 manifest repository on every update. 193 194 The <project> tags describe the projects to sync, and what state they should 195 sync to, accoring to the following attributes: 196 197 * name (required) - The name of the project. 198 199 * path (required) - The location where the project will be located, relative to 200 the jiri root. 201 202 * remote (required) - The remote url of the project repository. 203 204 * protocol (optional) - The protocol to use when cloning and syncing the repo. 205 Currently "git" is the default and only supported protocol. 206 207 * remotebranch (optional) - The remote branch that the project will sync to. 208 Defaults to "master". The "remotebranch" attribute is ignored if "revision" 209 is specified. 210 211 * revision (optional) - The specific revision (usually a git SHA) that the 212 project will sync to. If "revision" is specified then the "remotebranch" 213 attribute is ignored. 214 215 * gerrithost (optional) - The url of the Gerrit host for the project. If 216 specified, then running "jiri cl mail" will upload a CL to this Gerrit host. 217 218 * githooks (optional) - The path (relative to $JIRI_ROOT) of a directory 219 containing git hooks that will be installed in the projects .git/hooks 220 directory during each update. 221 222 * runhook (optional) - The path (relate to $JIRI_ROOT) of a script that will be 223 run during each update. 224 225 The <tool> tags describe the tools that will be compiled and installed in 226 $JIRI_ROOT/.jiri_root/bin after each update. The tools must be written in go, 227 and are identified by their package name and the project that contains their 228 code. They are configured via the following attributes: 229 230 * name (required) - The name of the binary that will be installed in 231 JIRI_ROOT/.jiri_root/bin 232 233 * package (required) - The name of the Go package that will be passed to "go 234 build". 235 236 * project (required) - The name of the project that contains the source code 237 for the tool. 238 `, 239 }