-
Notifications
You must be signed in to change notification settings - Fork 3k
Getting Started
This is intended to be a quick high-level overview of how to get started from scratch with HHVM on Linux, and not full documentation for any of the individual pieces mentioned. Refer to the rest of this wiki and the HHVM docs installation guide for full information on HHVM, and the documentation pages for other tools (such as nginx) for their full details.
The pieces you need to run code with HHVM are:
- HHVM itself
- A webserver such as nginx
- Some code to actually run
When a user makes a request for a PHP script on your server, nginx will terminate the HTTP request, see that it's referring to a PHP script, and then make a fastcgi request to HHVM. HHVM will process the request and send a response to nginx, which will then send the response to the original client. The "shape" of this process mirrors how php-fpm configurations work (except with HHVM instead of PHP5 on the back end of course), if you're familiar with that.
For this setup, although Debian, Ubuntu, and Mint are all supported with official packages, the most recent Ubuntu LTS and the most recent Ubuntu stable release are likely to be the best supported and easiest to get working. Furthermore, although any webserver, such as Apache or nginx, is supported, for simplicity this overview will talk only about nginx (since its configuration is dramatically simpler for our purposes). Again, feel free to read the full docs to figure out how to get Apache working.
Running sudo apt-get install nginx will get a working-enough nginx install on your system. At this point, you should be able to load http://localhost/ and get a page that says "Welcome to nginx!"
Refer to our directions on installing a prebuilt package. You can build from source if you really want, but doing that doesn't include nice things like our init script or automatic updates via apt-get, and so isn't recommended until you get a basic install working and have a better feel for what you're doing.
Each of the individual pages lists several packages you could install; sudo apt-get install hhvm is almost certainly the one you want. (The others are for bleeding-edge nightly releases, or for debugging HHVM itself.)
Installing HHVM will start it up now, but it won't be configured to start at next boot. sudo update-rc.d hhvm defaults will set that up.
Now, nginx and HHVM are both running, but they don't know how to talk to each other. The important part here is that nginx is what needs to be configured to know where your PHP files are and how to forward them to HHVM to execute. The relevant bit of nginx config lives at /etc/nginx/sites-available/default -- by default, it's looking in /usr/share/nginx/html for files to serve, but it doesn't know what to do with PHP.
Our included script sudo /usr/share/hhvm/install_fastcgi.sh will configure nginx correctly for stock installs. Refer to the full FastCGI documentation for all the details for more advanced settings and information. The important part is that it adds include hhvm.conf near the top of of the nginx config mentioned above -- this will direct nginx to take any file that ends in .hh or .php and send it to HHVM via fastcgi.
To test that everything is working, write this hello world script to hello.php in whichever directory nginx looks for its web files -- depending on OS, this may be /usr/share/nginx/html/hello.php or /var/www/html/hello.php or somewhere else:
<?php
echo "hello world\n";and then load http://localhost/hello.php and verify you see "hello world".
Note that by default /usr/share/nginx/html is only writable by root; use chown to set permissions as appropriate, or point /etc/nginx/sites-available/default at a different root, or refer to the nginx documentation to do something more fancy. Basically at this point you know things are working, so you can start from a known-good state as you start customizing your configuration, so it's easy to know if things break later which change broke it.
The out-of-the-box HHVM configuration won't need tweaking by most new users. Notably, the fancy JIT that gives HHVM its speed is on by default. If you want to take a look at the configuration, it's at /etc/hhvm/php.ini and /etc/hhvm/server.ini.
The only really interesting option for new users is in server.ini, the hhvm.log.file option, to control where your error logs go if the server hits a fatal error or similar. By default it's set to /var/log/hhvm/error.log.
The above will allow you to run Hack code as well; the only extra step is to make sure you are running the hh_client typechecker otherwise you'll be missing out on a lot of your type errors in your Hack code!
Actually learning to program in PHP or Hack is beyond the scope of this documentation. PHP's documentation contains an introduction to PHP, and there are numerous tutorials online. Hack has an online interactive tutorial.