Workflow Setup and Basic App Installation
To make Gall apps, it's important to work with your environment, not fight it. Below I outline your main workflow
I'll assume throughout this that we are using the
%home desk in a fake
~zod. If you
want to brush up on using
commit to manage Urbit piers, go here.
Below is a completely valid but very simple Gall program. You don't need to understand it yet: this
lesson is purely about our development workflow.
/+ default-agent ^- agent:gall =| state=@ |_ =bowl:gall +* this . default ~(. (default-agent this %|) bowl) :: ++ on-init ~& > ‘on-init’ on-init:default ++ on-save on-save:default ++ on-load ~& > ‘on-load’ on-load:default ++ on-poke |= [=mark =vase] ~& > state=state ~& got-poked-with-data=mark =. state +(state) `this :: ++ on-watch on-watch:default ++ on-leave on-leave:default ++ on-peek on-peek:default ++ on-agent on-agent:default ++ on-arvo on-arvo:default ++ on-fail on-fail:default –
Install Your First Gall App
To install a new program in Gall, you simply tell Gall its name with the
|start command, and Gall will
look for a Hoon file with that name in the
To see this, create a Hoon file called
my-gall-program.hoon in the
/app directory of your
home/app/my-gall-program.hoon) and paste the code above into it. Run the commands:
|commit |start %my-gall-program
You will see the output:
'on-init' = activated app home/my-gall-program [unlinked from [p=~zod q=%my-gall-program]]
Now let’s edit this app. Change the line
~& > 'on-load' to
~& > 'I just loaded'
|commit %home, and you should see:
commit %home = : /~zod/home/12/app/my-gall-program/hoon > 'I just loaded'
So we see here that once Gall has
started an app, it auto-reloads it whenever a new version of that
program is committed. We'll go more into this in the lifecycle lesson
Three Workflow Options
The install and editing process shown above will always be the same. However, if we simply develop apps in our pier,
we have to take care not to lose them if we start up a new
~zod for development.
There are 3 primary workflows we can use to handle this issue.
- YOLO: edit files directly in your mounted pier
- Create a separate folder, edit files there, and copy them to your pier
- Use the
create-landscape-appscripts to watch your project and sync files to your pier
Edit Files Directly in Your Pier
This will be familiar to anyone who has written simple Hoon generators. You write the code, commit it, and then run
it. Unfortunately, this makes it tricky to put our code in version control and to save it even when we make a new
~zod. I usually use this
Create a Separate Folder/Project
If you are writing a Gall app without a frontend (for example, a web server), you can create a separate folder
somewhere in your filesystem, edit files and track changes there, and then copy them to your pier.
This can be done at the command line like so:
cp -r your_code_directory/* your_pier_directory/app/
create-landscape-app to Sync Files to Your
Once we begin creating Landscape apps, we will able to use
create-landscape-app to monitor our JS and
Hoon files, and copy them to our ship as they're updated.
Faster Fakeship Startup
This can be used in combination with workflow option 1 above. Steps:
- Create a fake ship
|mount %as the first thing you do on the new fakeship
- Copy the pier directory to something like
- Do development as normal in method 1
- When you want to reset your ship, just delete your normal
zoddirectory (backing up code files of
course), and copy your
./urbit zodto boot from your backup, skipping the ~5 min load process.
Since Gall apps communicate between ships, it's sometimes useful in testing to make multiple ships and have them
talk to each other. This is really easy: any fake ships you have on your local machine can see each other
automatically. Just create them with
> ./urbit -F zod # in another terminal window: > ./urbit -F timluc
In the example above,
~timluc can now see each other. We'll use this
extensively starting in the poke and watch lesson.
Which Editor to Use?
Any text editor/IDE is fine for Hoon. VSCode has support for Hoon syntax highlighting, if you want that. I generally
keep a console with my Dojo open vertically next to my code, so that my editor takes up half the screen, and the
console half the screen. This works well with Hoon's vertically-oriented syntax.
In the introductory documents here, we will use approach (1) (editing files directly in your pier). Once we get to
the section on landscape apps, we will use those scripts. If you wish to create a separate directory for your files
throughout this and use approach (2), that is totally fine and up to you. Just remember to copy them to your pier
and commit each time you save.
Workflow Summary for Gall
- Have a fake
- Mount it to your Linux/Mac
- get your file with Gall code into
app, commit, and run
- every time you edit, make sure your new file ends up in
appand that you commit.