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 mount and commit to manage Urbit piers, go here.

Example Code

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-save   on-save:default
++  on-load
  ~&  >  ‘on-load’
++  on-poke
  |=  [=mark =vase]
  ~&  >  state=state
  ~&  got-poked-with-data=mark
  =.  state  +(state)
++  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 /app directory.


To see this, create a Hoon file called my-gall-program.hoon in the /app directory of your
pier (e.g. home/app/my-gall-program.hoon) and paste the code above into it. Run the commands:

|start %my-gall-program

You will see the output:

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'

Run |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.

  1. YOLO: edit files directly in your mounted pier
  2. Create a separate folder, edit files there, and copy them to your pier
  3. Use the create-landscape-app scripts 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/

Use 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:

  1. Create a fake ship
  2. Run |mount % as the first thing you do on the new fakeship
  3. Copy the pier directory to something like backup-zod
  4. Do development as normal in method 1
  5. When you want to reset your ship, just delete your normal zod directory (backing up code files of
    course), and copy your backup-zod directory to zod/.
  6. Run ./urbit zod to boot from your backup, skipping the ~5 min load process.

Multiple Ships

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 -F

> ./urbit -F zod

# in another terminal window:
> ./urbit -F timluc

In the example above, ~zod and ~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.

Our Approach

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 ~zod running
  • Mount it to your Linux/Mac
  • get your file with Gall code into app, commit, and run |start %YOURAPPNAME
  • every time you edit, make sure your new file ends up in app and that you commit.

Gall 101 Home | Next: The 10 Arms of Gaal: App Structure