c2a085c · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

make environment setup guide more comprehensive

c2a085cTinnus Napbus5 years ago

content/docs/development/environment.md+269−20

compare with master

unifiedsplit

@@ -8,25 +8,7 @@ template = "doc.html"

8This guide covers best practices for preparing your environment to develop

9within the Urbit ecosystem.

11−## Creating a development ship

12−

13−To do work with Hoon, we recommended using a "fake" ship — one that's not

14−connected to the network.

15−

16−Because such a ship has no presence on the network, you don't need an Azimuth

17−identity. You just need to have [installed the Urbit binary](/getting-started/cli).

18−

19−To create a fake ship named `~zod`, run the command below. You can replace `zod`

20−with any valid Urbit ship-name.

21−

22−```

23−./urbit -F zod

24−```

25−

26−This should take a couple of minutes, during which you should see a block of boot

27−messages, starting with the Urbit version number.

28−

29−## Hoon support in text editors

11+## Text editors

31A variety of plugins have been built to provide support for the Hoon language in

13A variety of plugins have been built to provide support for the Hoon language in

32different text editors:

14different text editors:

@@ -61,4 +43,271 @@ with [hoon-mode.el](https://github.com/urbit/hoon-mode.el).

62Vim is free and open-source and runs on all major operating systems. It is

44Vim is free and open-source and runs on all major operating systems. It is

63available [here](https://www.vim.org/). Hoon support is available with

45available [here](https://www.vim.org/). Hoon support is available with

64−[hoon.vim](https://github.com/urbit/hoon.vim) and is maintained by Tlon.

46+[hoon.vim](https://github.com/urbit/hoon.vim).

47+

48+## Development ships

49+

50+### Creating a fake ship

51+

52+To do work with Hoon, we recommended using a "fake" ship — one that's not

53+connected to the network.

54+

55+Because such a ship has no presence on the network, you don't need an Azimuth

56+identity. You just need to have [installed the Urbit binary](/getting-started/cli).

57+

58+To create a fake ship named `~zod`, run the command below. You can replace `zod`

59+with any valid Urbit ship-name.

60+

61+```

62+./urbit -F zod

63+```

64+

65+This should take a couple of minutes, during which you should see a block of boot

66+messages, starting with the Urbit version number.

67+

68+### Fake ship networking

69+

70+Fake ships on the same machine can automatically talk to one another. Having

71+created a fakezod, you can create a fake `~bus` the same way:

72+

73+```

74+./urbit -F bus

75+```

76+

77+Now in the fakezod's dojo, try:

78+

79+```

80+> |hi ~bus

81+>=

82+hi ~bus successful

83+```

84+

85+### Faster fake ship booting

86+

87+While working with Hoon, you'll often want to delete an old fake ship and

88+recreate a fresh one. Rather than having to wait a few minutes for the fresh

89+ship to be initialised, you can instead create a backup copy of a fake ship.

90+That way you can just delete the current copy, replace it with the backup, and

91+reboot in a matter of seconds.

92+

93+To do this, boot a fresh fake ship like usual, but with a different name:

94+

95+```

96+./urbit -F zod -c zod.new

97+```

98+

99+Once it's finished booting, it's a good idea to mount its desks so you don't

100+have to do it again each time. In the dojo:

101+

102+```

103+> |mount %base

104+>=

105+> |mount %garden

106+>=

107+> |mount %landscape

108+>=

109+> |mount %bitcoin

110+>=

111+> |mount %webterm

112+>=

113+```

114+

115+Next, shut the ship down with `ctrl+D`. Then, copy the pier and start using the

116+copy instead:

117+

118+```

119+cp -r zod.new zod

120+./urbit zod

121+```

122+

123+Now whenever you want a fresh fakezod, you can just shut it down and do:

124+

125+```

126+rm -r zod

127+cp -r zod.new zod

128+./urbit zod

129+```

130+

131+## Working with desks

132+

133+If you're just working in the dojo or experimenting with generators, committing

134+to the `%base` desk on a fake ship is fine. If you're working on a Gall agent or

135+developing a desk for distribution, you'll most likely want to work on a

136+separate desk and it's slightly more complicated.

137+

138+### Mount a desk

139+

140+To mount a desk to Unix so you can add files, you just need to run the `|mount`

141+command in the dojo and specify the name of the desk to mount:

142+

143+```

144+|mount %base

145+```

146+

147+The desk will now appear in the root of your pier (zod in this case):

148+

149+```

150+zod

151+└── base

152+```

153+

154+You can unmount it again by running the `|unmount` command in the dojo:

155+

156+```

157+|unmount %base

158+```

159+

160+### Create a new desk

161+

162+To create a new desk, you'll need to merge from an existing one, typically

163+`%base`. In the dojo, run the following (you can change `%mydesk` to your

164+preferred name):

165+

166+```

167+|merge %mydesk our %base

168+```

169+

170+If you now mount it, you'll have `/mydesk` directory in your pier with all the

171+files of the `%base` desk inside. You can then delete the contents, copy in your

172+own files and `|commit` it.

173+

174+Desks must contain all the `mark` files, libraries, etc, that they need. A

175+`sys.kelvin` file is mandatory, and there are a few `mark` files necessary as

176+well. In the next couple of sections we'll look at different ways to populate a

177+new desk with the necessary files.

178+

179+### Minimal desk

180+

181+This is the absolute minimal desk you'll be able to commit:

182+

183+```

184+skeleton

185+├── mar

186+│ ├── hoon.hoon

187+│ ├── kelvin.hoon

188+│ ├── mime.hoon

189+│ ├── noun.hoon

190+│ ├── txt-diff.hoon

191+│ └── txt.hoon

192+└── sys.kelvin

193+```

194+

195+`sys.kelvin` specifies the kernel kelvin version with which the desk is

196+compatible. You can copy it across from the `%base` desk, or just run the

197+following in the terminal from within the desk directory:

198+

199+```sh

200+echo "[%zuse 420]" > sys.kelvin

201+```

202+

203+The other `mark` files can just be copied across from the `%base` desk.

204+

205+### Using dev desks

206+

207+If you're working on something more complex, for example a desk with agents and

208+a front-end, there will be a number of `mark` files, libraries, etc, that will

209+be necessary. Rather than having to manually copy all the files from the

210+relevant default desks, the [urbit git repo](https://github.com/urbit/urbit)

211+includes some dev desks which can be used as a base. To get these, make sure you

212+have git installed and then clone the repo:

213+

214+```

215+git clone https://github.com/urbit/urbit ~/git/urbit

216+```

217+

218+If you now change to the `~/git/urbit/pkg` directory, you'll see the source for

219+the default desks, among other things:

220+

221+```

222+cd ~/git/urbit/pkg

223+```

224+

225+The desks ending in `-dev`, like `base-dev` and `garden-dev`, contain files for

226+interfacing with those respective desks. If you're creating a new desk that has

227+a tile and front-end, for example, you might like to use `base-dev` and

228+`garden-dev` as a base. To create such a base, there's a `symbolic-merge.sh`

229+script included in the directory. You can use it like so:

230+

231+```

232+./symbolic-merge base-dev mydesk

233+./symbolic-merge garden-dev mydesk

234+```

235+

236+After running that, you'll have a `mydesk` desk in the `pkg` directory that

237+contains the symlinked files from both those dev desks. To copy the files into

238+your pier, you can create and mount a mydesk desk in the dojo:

239+

240+```

241+|merge %mydesk our %base

242+|mount %mydesk

243+```

244+

245+Then, you can go into your pier:

246+

247+```

248+cd /path/to/fake/zod

249+```

250+

251+Delete the contents of `mydesk`:

252+

253+```

254+rm -r mydesk/*

255+```

256+

257+And then copy in the contents of the desk you created:

258+

259+```

260+cp -rL ~/git/urbit/pkg/mydesk/* mydesk

261+```

262+

263+Note you have to use `cp -rL` rather than just `cp -r` because the

264+`symbolic-merge.sh` script creates symlinks, so the `L` flag is to resolve them

265+and copy the actual files.

266+

267+Now you can just add a `sys.kelvin` file:

268+

269+```

270+echo "[%zuse 420]" > mydesk/sys.kelvin

271+```

272+

273+And you'll be able to mount the desk with `|commit %mydesk`.

274+

275+## Project organization

276+

277+When you're developing a desk, it's best to structure your working directory

278+with the same hierarchy as a real desk. For example, `~/project/mydesk` might

279+look like:

280+

281+```

282+mydesk

283+├── app

284+│ └── foo.hoon

285+├── desk.bill

286+├── desk.docket-0

287+├── lib

288+│ └── foo.hoon

289+├── mar

290+│ └── foo

291+│ ├── action.hoon

292+│ └── update.hoon

293+├── sur

294+│ └── foo.hoon

295+└── sys.kelvin

296+

297+```

298+

299+That way, whenever you want to test your changes, you can just copy it across to

300+your pier like:

301+

302+```

303+cp -ruv mydesk/* /path/to/fake/zod/mydesk

304+```

305+

306+And then just commit it in the dojo:

307+

308+```

309+|commit %mydesk

310+```

311+

312+If you're [using dev desks](#using-dev-desks) as a base, it's best to keep those

313+files separate from your own code.