github.com/comcast/canticle@v0.0.0-20161108184242-c53cface56e8/website/quickstart.html (about) 1 <!DOCTYPE html> 2 <html lang="en"> 3 <head> 4 <meta charset="utf-8"> 5 <meta http-equiv="X-UA-Compatible" content="IE=edge"> 6 <meta name="viewport" content="width=device-width, initial-scale=1"> 7 <!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags --> 8 <meta name="description" content=""> 9 <meta name="author" content=""> 10 <link rel="icon" href="favicon.ico"> 11 12 <title>Canticle</title> 13 14 <!-- Bootstrap core CSS --> 15 <link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css"> 16 <script src="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/ie-emulation-modes-warning.js"></script> 17 18 <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries --> 19 <!--[if lt IE 9]> 20 <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script> 21 <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script> 22 <![endif]--> 23 24 <!-- Custom styles for this template --> 25 <link href="carousel.css" rel="stylesheet"> 26 </head> 27 <!-- NAVBAR 28 ================================================== --> 29 <body> 30 <nav class="navbar navbar-inverse navbar-fixed-top"> 31 <div class="container"> 32 <div class="navbar-header"> 33 <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> 34 <span class="sr-only">Toggle navigation</span> 35 <span class="icon-bar"></span> 36 <span class="icon-bar"></span> 37 <span class="icon-bar"></span> 38 </button> 39 <a class="navbar-brand" href="index.html"><img height="40" src="cant.png" /></a> 40 </div> 41 <div id="navbar" class="navbar-collapse collapse"> 42 <ul class="nav navbar-nav"> 43 <li><a href="index.html">Home</a></li> 44 <li><a href="about.html">About</a></li> 45 <li class="active dropdown"> 46 <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Quick Start Guides<span class="caret"></span></a> 47 <ul class="dropdown-menu"> 48 <li><a href="quickstart.html#library">Library</a></li> 49 <li><a href="quickstart.html#project">Project</a></li> 50 <li><a href="quickstart.html#workspace">Workspace</a></li> 51 </ul> 52 </li> 53 <li class="dropdown"> 54 <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Docs<span class="caret"></span></a> 55 <ul class="dropdown-menu"> 56 <li class="dropdown-header">Canticle</li> 57 <li><a href="docs.html#cant"><code>cant</code></a></li> 58 <li role="separator" class="divider"></li> 59 <li class="dropdown-header">Commands</li> 60 <li><a href="docs.html#cantget"><code>cant get</code></a></li> 61 <li><a href="docs.html#cantsave"><code>cant save</code></a></li> 62 <li><a href="docs.html#cantvendor"><code>cant vendor</code></a></li> 63 <li><a href="docs.html#cantgenversion"><code>cant genversion</code></a></li> 64 <li role="separator" class="divider"></li> 65 <li class="dropdown-header">Internals</li> 66 <li><a href="docs.html#canticlefile">Canticle Files</a></li> 67 <li><a href="docs.html#vcs">VCS Commands</a></li> 68 </ul> 69 </li> 70 </ul> 71 <ul class="nav navbar-nav pull-right"> 72 <li class="icon-bar"><a title="sauce" href="http://github.com/Comcast/Canticle"><img src="https://assets.github.com/images/icons/emoji/octocat.png" /></a></li> 73 <li class="icon-bar"><a title="sauce" href="http://careers.stackoverflow.com/company/comcast-viper"><img src="ComcastFrog-VIPER-black.svg" /></a></li> 74 </ul> 75 </div> 76 </div> 77 </nav> <!-- /navbar --> 78 79 <div class="container marketing"> 80 <div class="container"> 81 <h1 id="library">Library Quick Start</h1> 82 <h2>Manage a Library</h2> 83 <p>As a library maintainer you may need to save a certain revision, tag, 84 or branch of a project you rely on.</p> 85 <ol> 86 <li>Checkout out your dependencies using your normal workflow. You can use <code>go get</code>, <code>cant vendor</code>, or <code>gb vendor</code>.</li> 87 <li>Save the deps and versions using the <a href="docs.html#cantsave">save</a> command. At the root of your project run:</li> 88 <pre>cant save -no-sources</pre> 89 90 If you want to save a branch (say release/1.2.0) just run: 91 <pre>cant save -b -no-sources</pre> 92 <li>Commit the <code>Canticle</code> file.</li> 93 </ol> 94 <h3>What's Happening</h3> 95 <p>In the first example we run <code>cant save -no-sources</code>. This code walks our dependency tree and saves the current revisions of each VCS. The result is saved in our <code>Canticle</code> file. The <code>-no-sources</code> flag tells Canticle not to save where the the repo was checked out from. Users of your library may want to source it from somewhere else (say in a private git repo).</p> 96 <p><code>cant save</code> also walks <i>down</i> the folder hierarchy. This means even if you have no buildable go files in the root of your project, or part of the project isn't imported by the main, its dependencies will still be included. To not traverese into a directory use `-exclude <dir>`.</p> 97 <h2>Use a Library</h2> 98 <ol> 99 <li>Vendor a library and its suggested dependencies: <pre>cant vendor <package name></pre></li> 100 <li>Save the dependency information for your <a href="#project">project</a>.</li> 101 </ol> 102 </div> 103 104 <hr class="featurette-divider"> 105 106 <div> 107 <h1 id="project">Project Quickstart</h1> 108 <h2>Manage a Project</h2> 109 <p>If you maintain a single project with many dependencies for your 110 company it: probably needs to be checked into an internal rep and 111 probably needs revision locks. For this we:</p> 112 113 <ol> 114 <li>Vendor the dependency using the <a href="docs.html#cantvendor">vendor</a> command: 115 <pre>cant vendor <external_repo></pre> 116 </li> 117 <li>(Optional) Import a copy into your internal repos. In git we might do this 118 like so: 119 <pre>git remote rm origin 120 git remote add origin <internal_repo> 121 git push -u origin --all</pre> 122 </li> 123 124 <li>Save the project deps: 125 <pre>cd $GOHOME/<your_project> 126 cant save</pre> 127 If conflicts exists (multiple specified vcs sources or revisions) you 128 will be prompted for resolution. To prefer whats on disk now simply do 129 <code>cant save -ondisk</code>. 130 </li> 131 132 <li>Check in the resulting <code>Canticle</code> file.</li> 133 134 <li>Work with the project like normal. New developers can simply: 135 <pre>cd $GOHOME/<your_project> 136 cant get</pre> 137 and all of your repos will be pulled at the correct revision, from the 138 correct source (your internal repo). 139 </li> 140 </ol> 141 <h2>Use a Project</h2> 142 <ol> 143 <li>Get a project dependencies. Go to the project directory and use the <a href="docs.html#cantget">get</a> command: 144 <pre>cd $GOHOME/<your_project> 145 cant get</pre></li> 146 <li>Generate build information using <a href="docs.html#cantgenversion">genversion</a>. Go the the package main for the project: 147 <pre>cant genversion 148 git add buildinfo/buildinfo.go 149 git commit -m "Add base for generated build info" 150 </pre> </li> 151 <li>If you need to update a dependency checkout the revision you want and got to step 3 of "Manage a Project".</li> 152 </ol> 153 </div> 154 155 <hr class="featurette-divider"> 156 <div> 157 <h1 id="workspace">Workspace Quickstart</h1> 158 <h2>Manage a Workspace</h2> 159 <p>If you have a microservice architecture you probably need to 160 manage the version of a lot of artifacts at once. Many of them 161 may share common build time dependencies which should be version 162 locked across projects. Canticle lets you version a workspace as 163 well.</p> 164 <ol> 165 <li>Go to the <code>src</code> directory of your workspace <pre>cd $GOHOME/src</pre></li> 166 <li>Save the versions of your workspace. Exclude directories 167 whose deps don't matter to your project. 168 <pre>cant save -b -exclude golang.org -exclude github.com</pre></li> 169 <li>Check in your workspace. It should be rooted at $GOHOME. In git we would do this: 170 <pre>cd $GOHOME 171 git init 172 git add src/Canticle 173 git commit -m "Initial commit"</pre> 174 </li> 175 </ol> 176 <h3>What's Happening</h3> 177 <p> We are saving just the deps in the workspace we care 178 about. For example many projects rely 179 on <code>golang.org/x/net/context</code>, but they won't 180 want to keep every dependency of <code>x/net</code>. If a 181 package is in the dependency graph for a project it will 182 still be saved. So if you use <code>x/net</code> it will be 183 saved, but not the dependencies not directly related to the 184 project. 185 </p> 186 <p>In addition we have specified <code>-b</code> to save 187 branches where we can. That means only the projects you want 188 revison locked will be.</p> 189 <h2>Use a Workspace</h2> 190 <ol> 191 <li>To use a workspace check it out, go into 192 the <code>src</code> directory and use Canticle to pull all 193 projects and dependencies. 194 <pre>cd <project>/src 195 cant get</pre></li> 196 <li>Update the workspace frequently: 197 <pre>cd <project>/src 198 cant get -u</pre></li> 199 <li>Change multiple projects and ask for a code 200 reviews. Save your changes on branches for each repo and 201 follow the steps in "Manage a workspace".</li> 202 </ol> 203 204 </div> 205 <hr class="featurette-divider"> 206 207 </div> 208 209 210 <div class="container marketing"> 211 <!-- FOOTER --> 212 <footer> 213 <p class="pull-right"><a href="#">Back to top</a></p> 214 </footer> 215 216 </div><!-- /.container --> 217 218 219 <!-- Bootstrap core JavaScript 220 ================================================== --> 221 <!-- Placed at the end of the document so the pages load faster --> 222 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> 223 <script src="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script> 224 <!-- Just to make our placeholder images work. Don't actually copy the next line! --> 225 <!-- IE10 viewport hack for Surface/desktop Windows 8 bug --> 226 <script src="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/ie10-viewport-bug-workaround.js"></script> 227 </body> 228 </html>