ZX: Installation

Before you can use ZX you need two things:

  1. The Erlang runtime
  2. ZX

Getting Erlang

For *nix users (Linux, Unix, BSD, OSX, etc.)

You have a few options:

For Windows users

Go to the Erlang downloads page and get the Windows installer that suits your system.
(Protip: most modern systems are 64-bit.)

Getting ZX

The Sith Method

If you are on a unix type system and already have Erlang installed, the easiest way to install ZX is by running the following command and you'll be all set!

wget -q https://zxq9.com/projects/zomp/get_zx && bash get_zx

(The command above simply automates the steps shown below.)

The Jedi Path

Go to the ZX download page and get the installation bundle. Follow the instructions for *nix or Windows below.

Linux/BSD/OSX/Unix/*nix

Steps:

  1. wget https://zxq9.com/projects/zomp/zx-0.9.1.tar.xz
  2. tar -Jxf zx-0.9.1.tar.xz
  3. cd zx-0.9.1
  4. chmod +x install
  5. ./install

Note: If you do not have XZ on your system you'll need the gzipped bundle.

Here is a log of what you should experience should everything go well (-q is used to silence wget's output -- it does not change anything):

everett@cake:~$ wget -q https://zxq9.com/projects/zomp/zx-0.9.1.tar.xz
everett@cake:~$ tar -Jxf zx-0.9.1.tar.xz 
everett@cake:~$ cd zx-0.9.1/
everett@cake:~/zx-0.9.1$ ./install 
Erlang found at /home/everett/.erts/22.2/bin/erl
/home/everett/bin was found in $PATH. Good to go.
Path adjustment found in /home/everett/.profile.
Path adjustment found in /home/everett/.bashrc.
No /home/everett/.bash_profile is present. Skipping.
zx found at /home/everett/bin/zx. Checking for upgrade.
Running `zx upgrade`...
Recompile: src/zx_zsp
Recompile: src/zx_userconf
Recompile: src/zx_tty
Recompile: src/zx_sup
Recompile: src/zx_proxy
Recompile: src/zx_peers
Recompile: src/zx_peer_sup
Recompile: src/zx_peer_man
Recompile: src/zx_peer
Recompile: src/zx_net
Recompile: src/zx_local
Recompile: src/zx_lib
Recompile: src/zx_key
Recompile: src/zx_daemon
Recompile: src/zx_conn_sup
Recompile: src/zx_conn
Recompile: src/zx_auth
Recompile: src/zx
Current version: otpr-zx-0.9.1
Running latest version.
everett@cake:~/zx-0.9.1$ cd ..
everett@cake:~$ rm -rf zx-0.9.1*

From this point you should be able to use ZX from the command line!

YAY! You're ready to do stuff!

It is a good idea to run zx upgrade periodically to make sure you have the latest version.

Windows

Windows interfaces with ZX and Zomp via a graphical front-end called Vapor. The Windows installer for ZX is called "InstallVapor.exe" for this reason, and installs both ZX and Vapor, adding links from the desktop to Vapor.

Launching programs through Vapor is perfectly comfortable, but many developer functions are difficult to make work properly with the Windows cmd.exe terminal (though Bash implementations such as the one that comes with "Git for Windows" make things much easier). Until Vapor's support extends to the developer features, it is best to consider Windows as an "end-user" platform and not suitable for developers using ZX just yet.

ZX commands can be used from the command line in Windows, but currently require being invoked from the user's %USERPROFILE% (usually C:\Users\[username]\ -- wherever cmd.exe starts by default) as zx.lnk [command] or zxh.lnk [command] instead of the cleaner zx [command]. The reason for this is that the Vapor installer does not update your Windows %PATH% variable. (You may update your path to include %LOCALAPPDATA%\zomp\, however.)

Vapor on Windows is still itself in beta, so you will encounter a few rough edges, such as the console window being opened when you click "Vapor", and a slowing expanding feature set. The good news is that Vapor will automatically update itself every time it is run.

Uninstallation

Linux/BSD/OSX/Unix/*nix

Run $HOME/zomp/uninstall. It will remove the symlinks in $HOME/bin and the entire $HOME/zomp directory.

Windows

The installer registers Vapor with the Windows registry the normal way and provides an uninstaller. Select "uninstall" from the normal "Applications" configuration menu within Windows, or find C:\Users\[username]\AppData\Local\zomp\uninstall.exe and run it.

Unix Notes for Developers and Sysops

ZX installs to $HOME/zomp/ and creates symlinks to zx (headless) and zxh (with erl shell) at $HOME/bin/ by default. This behavior can be changed, of course, and those wishing to run system services built and launched by ZX will usually want to move their installations to a custom location (creating a service user account and installing ZX as that user with $HOME set to a custom location simplifies this).

The start script for ZX sets an environment variable $ZOMP_DIR to $HOME/zomp/ if it is not already set. If you want to install to a custom location that is not the $HOME of the user account that will be executing it (for system services, for example) then your start procedure will need to set the environment variable before calling the zx launch script.

The main thing to remember is that ZX doesn't care where it is installed or who it is run by because it should never ask for system privileges and only requires that the execution scripts can locate an Erlang runtime.

Doing Stuff

Once you've got an Erlang runtime and ZX in your $PATH, you can do stuff (like running programs!).

A list of common tasks and workflows is back on the quickstart page.

The comprehensive ZX user manual page has more technically exhaustive explanations and covers every command, but not everyone really needs to read all of it.

Feedback

To provide feedback directly to the author look for me (Craig Everett, aka "zxq9") at: