{"id":13547932,"url":"https://github.com/urbit/archaeology","last_synced_at":"2025-10-19T07:32:31.218Z","repository":{"id":72682668,"uuid":"12135920","full_name":"urbit/archaeology","owner":"urbit","description":"An Operating Function","archived":false,"fork":false,"pushed_at":"2014-08-29T01:28:34.000Z","size":394677,"stargazers_count":329,"open_issues_count":8,"forks_count":41,"subscribers_count":73,"default_branch":"master","last_synced_at":"2025-03-27T02:11:40.471Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"www.urbit.org","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urbit.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-08-15T14:13:11.000Z","updated_at":"2025-01-03T16:40:14.000Z","dependencies_parsed_at":"2023-02-23T17:45:23.715Z","dependency_job_id":null,"html_url":"https://github.com/urbit/archaeology","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbit%2Farchaeology","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbit%2Farchaeology/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbit%2Farchaeology/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbit%2Farchaeology/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urbit","download_url":"https://codeload.github.com/urbit/archaeology/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248703195,"owners_count":21148117,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T12:01:03.279Z","updated_at":"2025-10-19T07:32:31.136Z","avatar_url":"https://github.com/urbit.png","language":"C","funding_links":[],"categories":["C","others"],"sub_categories":[],"readme":"Urbit\n=====\n\n[![Build Status](https://travis-ci.org/urbit/urbit.png?branch=master)](https://travis-ci.org/urbit/urbit)\n\n\u003e Tlön is surely a labyrinth, but it is \n\u003e a labyrinth devised  by men, a labyrinth \n\u003e destined to be deciphered by men.  \n\u003e -- Tlön, Uqbar, Orbis Tertius\n\nUrbit is a new programming and execution environment designed from scratch. Any\nresemblance to existing languages or operating systems is coincidental,\ncosmetic, or inevitable.\n\nInstall\n-------------------\n\n###1. Dependencies\n\nUrbit depends on:\n\n    gcc\n    gmp\n    libsigsegv\n    openssl\n    libssl-dev (Linux only)\n    ncurses (Linux only)\n\n####Ubuntu or Debian\n\n    sudo apt-get install libgmp3-dev libsigsegv-dev openssl libssl-dev libncurses5-dev git make exuberant-ctags\n\n####Fedora\n\n    sudo yum install gcc gcc-c++ git gmp-devel openssl-devel openssl ncurses-devel libsigsegv-devel ctags\n\n####AWS\n\n    sudo yum --enablerepo epel install gcc git gmp-devel openssl-devel ncurses-devel libsigsegv-devel ctags\n\n####OS X\n\nDo you have XCode? Type `gcc` at your terminal prompt.\n\nIf it says `no input files`, you have XCode.\n\nOtherwise, install XCode: `https://developer.apple.com/xcode/`, with the command line tools.\n\nTo install dependencies pick either one of Homebrew or Macports, but not both:  \n  Homebrew -  \n  `brew install git gmp libsigsegv openssl`  \n\n  Macports -  \n  `sudo port install git gmp libsigsegv openssl`\n\n\n###2. Build\n\nClone this repo:\n\n    git clone git://github.com/urbit/urbit.git\n\n`cd` to the unpacked Urbit directory you just created:\n\n    cd urbit\n\nIf this works, `ls urb/` should show:\n\n    urbit.pill  zod/\n\nThen just run `make` in the urbit directory.\n\nSometimes things are just easy.\n\n\n###3. Run\n\nRun `bin/vere -c mypier` in the urbit directory, where `mypier` is a directory that doesn't yet exist. All your state (an append-only log and a memory checkpoint) will live in this directory.  The name of your pier doesn't matter and is not visible internally.\n\nA _pier_ is an Urbit virtual machine that hosts one or more Urbit identities,\nor _ships_.  When you run `bin/vere -c`, it automatically creates a 128-bit ship, or `submarine`.  Your name (a hash of a randomly-generated public key) will look something like:\n\n    ~machec-binnev-dordeb-sogduc--dosmul-sarrum-faplec-nidted\n\nFirst you'll see a string of messages like:\n\n    vere: urbit home is /Users/cyarvin/Documents/src/u3/urb\n    loom: mapped 1024MB\n    time: ~2013.9.1..03.57.11..4935\n    ames: on localhost, UDP 63908.\n    generating 2048-bit RSA pair...\n\nand then it'll pause a little, 'cause this is slow, and then\n\n    saving passcode in /Users/cyarvin/.urbit/~magsut-hopful.txt\n    (for real security, write it down and delete the file...)\n\nand, then, if the network gods are happy, your submarine will start pulling\ndown Arvo files:\n\n     + /~machec-binnev-dordeb-sogduc--dosmul-sarrum-faplec-nidted/main/1/bin/ticket/hoon\n     + /~machec-binnev-dordeb-sogduc--dosmul-sarrum-faplec-nidted/main/1/bin/reset/hoon\n     + /~machec-binnev-dordeb-sogduc--dosmul-sarrum-faplec-nidted/main/1/bin/ye/hoon\n     + /~machec-binnev-dordeb-sogduc--dosmul-sarrum-faplec-nidted/main/1/bin/ls/hoon\n\nand the like.  You'll see a couple pages of this stuff.  Don't worry too much\nabout the details right now.  Finally, you'll get the Arvo shell prompt (which\nis also a Hoon REPL):\n\n    ~machec-binnev-dordeb-sogduc--dosmul-sarrum-faplec-nidted/try=\u003e\n\nIf you would like to safely bring this ship back into port (End the Unix process),\njust enter Control-D.  \n\n\n###4. Registration\n\nArvo instances in the Urbit network, called \"ships\", are addresses in a finite namespace much like IP numbers.  You should be able to remember your personal IP number. However, numbers are cumbersome for humans to memorize.  Urbit solves this problem by mapping each address to a phonetic name, whose length is proportional to how many of that type of ship there are.  \n\nIn this section, we'll get you registered with some Urbit ships. One of these ships, a destroyer, will be both your personal cloud computer and identity in the social network of Urbit.\n\nThe long name in your prompt now is that of a submarine. Submarines are  cheap, temporary ships that are tiring to remember but useful for trying Urbit out or browsing anonymously. But this moniker is mouthful.  You can stick with it for now, but you're going to need a wider xterm.\n\nInstead, registering for a destroyer will get you a nice short name like\n\n    ~waclux-tomwyc\n\nDestroyers are rarer ships meant to be associated with a user's digital identity. They are far fewer destroyers in the Urbit namespace than submarines. \n\nTlon would be glad to give you a destroyer from the batch that they own. Head over to [tlon.io](http://tlon.io) to complete the automated registration process. \n\nYour destroyers will arrive in the form of `[ship ticket]` pairs.\nLet's say one of your ships is `~waclux-tomwyc` and its ticket is\n\n    ~ribdyr-famtem-larrun-figtyd\n\n(Where do we get these phonetic strings from, anyway?  Just random unsigned integers,\nrendered in Hoon's syllabic base, `@p`.)\n\nA new life awaits you on the off-world colonies!  To begin, just\ntype at the submarine prompt:\n\n    :begin ~waclux-tomwyc\n\nand follow the directions.  When the script completes, hit return\nand you'll be the `~waclux-tomwyc` you wanted to be.  Now, when other user's see you in chat or look at your \nUrbit social profile (a fasplan), they can learn whatever information you gave the :begin process.\n\n###5. Play with Arvo\n\nIf all went well, you now have a nice short prompt:\n\n    ~waclux-tomwyc/try=\u003e\n\nIf all did not go well (send us another email), or you're just\ntoo impatient to wait for your destroyer, you have a big long\nprompt.  Which is fine, really, just ugly - and all these\nexercises will still work.\n\n####Example commands\n\nLet's try a few quick things to stretch your fingers.  Type these\ncommand lines and you should see the matching results:\n\n    ~waclux-tomwyc/try=\u003e \"hello, world\"\n    \"hello, world\"\n\n    ~waclux-tomwyc/try=\u003e (add 2 2)\n    4\n\n    ~waclux-tomwyc/try=\u003e :hello %world\n    \"hello, world.\"\n\n    ~waclux-tomwyc/try=\u003e :cat /=main=/bin/hello/hoon\n    ::\n    ::  /=main=/bin/hello/hoon\n    ::\n    |=  *\n    |=  [planet=@ta ~]\n    ^-  bowl\n    :_  ~  :_  ~\n    :-  %%\n    !\u003e(\"hello, {(trip planet)}.\")\n\nWhat did you just do?\n\nOne, you used Arvo as a Hoon REPL to print the constant `\"hello,\nworld\"`, which is a fancy way to write the Nock noun\n\n    [104 101 108 108 111 44 32 119 111 114 108 100 0]\n\nTwo, you called the Hoon `add` function to see that two plus two\nis four.  Math seems to work the same on the off-world colonies.\n\nThree, you ran the Arvo application `:hello` with the argument\n`%world`, which is just a fancy way to write the atom\n`431.316.168.567` (or, for non-Germans, `431,316,168,567`).  You\nmight recognize it better as `0x64.6c72.6f77` - the ASCII\ncharacters in LSB first order.\n\n(Is Urbit German?  Sadly, no.  But all our noun print formats are\nURL-safe, which dot is and comma isn't.)\n\nAnd you (4) used the Arvo application :cat to print the Hoon file\n\n    /=main=/bin/hello/hoon\n\nwhich, supposing your current date is\n\n    ~2013.9.1..04.38.31..f259\n\n(ie, September 1, 2013 at 4:38:31 GMT/LS25 plus 0xf259/65536\nseconds), is equivalent to the global path\n\n    /~waclux-tomwyc/main/~2013.8.23..04.38.31..f259/bin/hello/hoon\n\nwhich anyone in Urbit can, see and even use - but we're getting\nahead of ourselves.\n\n####Control characters\n\nIn any case, what we've seen is that Arvo is a dangerous and\npowerful operating system which if handled improperly can cause\nserious injury or loss of life.  We exaggerate.  Slightly.\n\nThe first thing you need to know is how to control this tool.\nTry your arrow keys - you'll see that Arvo has traditional Unix\nhistory editing.  Up and down, left and right work, as do the\nsimple emacs controls:\n\n    ^A  go to beginning of line\n    ^B  left arrow\n    ^D  delete next character\n    ^E  go to end of line\n    ^F  right arrow\n    ^K  kill to end of line\n    ^L  clear the screen\n    ^R  search through history\n    ^U  kill the whole line\n    ^Y  yank (restore from kill ring)\n\nDon't expect any other emacs (or even readline - this is not readline, it's\ninternal to Arvo) commands to work.\n\nThere are also some special control keys specific to Arvo.  It's\na good idea to learn these first so that you feel in, um,\ncontrol.\n\nFirst, we'll quit out of an infinite loop with `^C`:\n\n    ~waclux-tomwyc/try=\u003e :infinite\n\nWhen you hit return at the end of this line, Arvo will appear to\nhang.  Do not be alarmed!  This is not a bug - it means that\nwe've started running our infinite loop before printing the next\nconsole prompt.  Simply hit `^C`, and you'll see\n\n    ! intr\n    ~waclux-tomwyc/try=\u003e :infinite\n\n(There may be some stacktrace stuff before the `! intr`, depending\non whether your kernel was compiled with debugging.)\n\nHit `^U` to delete the line and escape from infinity.  Arvo is a\ndeterministic OS; you interrupted it while processing an event\nthat would never terminate.  It returns to the state it was in\nbefore you hit return - as if nothing had ever happened.\n\nYou're probably used to using nondeterministic, preemptive OSes,\nin which the difference between a waiting task and an\nexecuting event isn't apparent to the user.  Since Arvo is not\npreemptive, it has two very different states: waiting and\nworking.\n\nWhen Arvo is working, `^C` cancels the event it's working on.\nThis event never happened.  Don't worry, nothing bad will happen\nto your computer.\n\nWhen Arvo is waiting, use `^D` to end the current task, which is\nthe task that's currently prompting you.  If there is a live\nprompt and the cursor is not at the end, `^D` will delete the\ncurrent character - as in Unix.\n\nTry this by running\n\n    ~waclux-tomwyc/try=\u003e :begin\n\n    Do you have a ship and a ticket? yes\n\nThen hit `^D` and you'll be back to the command prompt (which,\nunlike in Unix, is not a task itself, but part of the OS).\n\nWe don't always want to kill the prompting task.  We often want\nto switch between tasks, or between tasks and the command line.\nSort of like switching between windows, except in a command line.\nWe do this with `^X`.  Try\n\n    ~waclux-tomwyc/try=\u003e :begin\n\n    Do you have a ship and a ticket? yes\n\nBut hit `^X` instead of `^D`.  You'll get a prompt again.  Use\nit:\n\n    ~waclux-tomwyc/try=\u003e :begin\n\n    ~waclux-tomwyc/try=\u003e :hello %world\n    \"hello, world.\"\n    ~waclux-tomwyc/try=\u003e\n\nHit `^X` again:\n\n    ~waclux-tomwyc/try=\u003e :begin\n\n    ~waclux-tomwyc/try=\u003e :hello %world\n    \"hello, world.\"\n    Do you have a ship and a ticket? yes\n\nAnd finally, hit `^C` to kill the task.\n\nLastly, Arvo is a single-level store.  Since it's not the '70s\nanymore and disk is cheap, everything you do is saved for ever.\n(In fact, it's saved in two ways - as a memory image and an event\nlog - so you, or the government if they haz your filez, can\nrepeat every computation you've ever performed.)\n\nIf the current prompt is just the shell prompt, `^D` on an empty\nline will log out - as in Unix:\n\n    ~waclux-tomwyc/try=\u003e\n    oxford:~/urbit; pwd\n    /Users/cyarvin/urbit\n    oxford:~/urbit; echo \"hello, world\"\n    hello, world\n    oxford:~/urbit;\n\nThen you can restart and be right back where you were - just\nrun `bin/vere` without `-c`:\n\n    oxford:~/urbit; bin/vere mypier\n    vere: urbit home is /Users/cyarvin/urb\n    loom: loaded 9MB\n    time: ~2013.9.1..17.23.05..0cc1\n    ames: on localhost, UDP 60342.\n    http: live on 8080\n    rest: checkpoint to event 383\n    rest: old 0v1c.gkr1o, new 0v10.m4gdu\n    ---------------- playback complete----------------\n    waclux-tomwyc/try=\u003e\n\nUse your arrow keys and you'll see your history is still there.\nArvo is indestructible and can be shut down however you like\nwithout losing data.  Also, starting a new task while an old\none is still running will kill the old one safely.\n\nBut don't try to operate the same ship on two Unix hosts at the\nsame time.  This will confuse everyone, including yourself.\n\n####System administration\n\nSometimes we make changes to Hoon or Arvo (we never make changes\nto Nock) and you need to update your ship.\n\nThere are two steps to updating.  You need to get the new files,\nand you need to install them.  To get them:\n\n    ~waclux-tomwyc/try=\u003e :update\n    : /~waclux-tomwyc/arvo/2/hoon/hoon\n    : /~waclux-tomwyc/arvo/2/dill/hoon\n    : /~waclux-tomwyc/arvo/2/batz/hoon\n\nTo install them (the simplest, slowest, most general way):\n\n    ~waclux-tomwyc/try=\u003e :reset\n\n    %reset-start\n    %reset-parsed\n    %reset-compiled\n    %hoon-load\n    [%tang /~waclux-tomwyc/arvo/~2013.11.26..20.29.15..090f/zuse ~tirnux-latwex]\n    [%vane %a /~waclux-tomwyc/arvo/~2013.11.26..20.29.15..090f/ames ~tolryn-watret]\n    [%vane %b /~waclux-tomwyc/arvo/~2013.11.26..20.29.15..090f/batz ~donfex-ladsem]\n    [%vane %c /~waclux-tomwyc/arvo/~2013.11.26..20.29.15..090f/clay ~picsug-mitref]\n    [%vane %d /~waclux-tomwyc/arvo/~2013.11.26..20.29.15..090f/dill ~dilpex-laptug]\n    [%vane %e /~waclux-tomwyc/arvo/~2013.11.26..20.29.15..090f/eyre ~forbur-disben]\n\nAll of your state, including running tasks, will be unchanged.\n\nSometimes the interpreter, called `vere` gets updated. In your urbit directory, back in Unixland, run:\n\n    git pull origin master\n\nevery so often to get the latest Urbit source code. You'll need to run:\n\n    make clean; make\n\nbefore executing `bin/vere pier` again.\n\n\n###6. Chat\n\nOkay, fine.  You're a long way from being an Arvo ninja.  But -\nyou're ready for the two most important uses of Urbit right now.\nOne, coding.  Two, chatting.\n\nTo start chatting, simply type\n\n    ~waclux-tomwyc/try=\u003e :chat\n\n\nand type `?` for the list of commands once `:chat` is running. \n\nMost of us are hanging out on `:chat` regularly. We can answer any questions you might have and help you get oriented in this new environment.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furbit%2Farchaeology","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furbit%2Farchaeology","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furbit%2Farchaeology/lists"}