1 hhvm stores serialized HipHop Bytecode and metadata in on-disk repositories, or
2 "repos" for short. Repos are implemented using SQLite (http://www.sqlite.org/),
3 which means that repo introspection is possible using the sqlite3 command line
4 program, as well as via SQLite API bindings for any number of programming
5 languages. For example, here is how to determine the schema within a repo named
8 $ sqlite3 hhvm.hhbc '.schema'
10 This dumps the SQLite database schema, but the repo schema is a slightly
11 different concept, in that one repo can support multiple repo schemas
12 simultaneously. To make this possible, every SQLite table name is suffixed with
13 the repo schema version, which is normally based on the source code and
14 relevant options used to compile the runtime. For example, repo schema
15 77fae842fab099b2eb4771f620e15a4bbf3883aa contains a table called
16 "magic_77fae842fab099b2eb4771f620e15a4bbf3883aa":
18 $ sqlite3 hhvm.hhbc '.dump magic_77fae842fab099b2eb4771f620e15a4bbf3883aa'
19 PRAGMA foreign_keys=OFF;
21 CREATE TABLE magic_77fae842fab099b2eb4771f620e15a4bbf3883aa(product TEXT);
22 INSERT INTO "magic_77fae842fab099b2eb4771f620e15a4bbf3883aa"
23 VALUES('facebook.com HipHop Virtual Machine bytecode repository');
26 This table is used as a sanity check to assure that the repo is initialized to
29 hhvm utilizes SQLite transactions to ensure that the repo is always in a
30 consistent state. For example, the repo schema is either fully in place or fully
31 absent. The same is true for compilation units; if an entry exists in the
32 Unit_77fae842fab099b2eb4771f620e15a4bbf3883aa table, then all the associated
33 data exists in the other tables.
35 $ sqlite3 hhvm.hhbc '.dump Unit_77fae842fab099b2eb4771f620e15a4bbf3883aa'
36 PRAGMA foreign_keys=OFF;
38 CREATE TABLE Unit_77fae842fab099b2eb4771f620e15a4bbf3883aa(
39 unitSn INTEGER PRIMARY KEY, md5 BLOB, bc BLOB,
40 mergeable INTEGER,lines BLOB, UNIQUE (md5));
43 Rather than use the bulky md5 blob as a unique identifier throughout the repo,
44 unitSn is used. Incidentally, here is how to find out how many compilation units
47 $ sqlite3 hhvm.hhbc 'SELECT COUNT(*)
48 FROM Unit_77fae842fab099b2eb4771f620e15a4bbf3883aa;'
51 hhvm uses one or two repos, depending on configuration. The 'central' repo must
52 always be writeable, but the 'local' repo can be read-only, or even completely
53 missing. Before opening either the central or local repo, the first occurrence
54 of '%{schema}' in the path will be replaced by the current schema id. There are
55 several runtime configuration options (and related environment variables) that
56 can be used to control repo behavior:
58 * Repo.Local.Mode: rw, r-(*), or -- (overrides HHVM_REPO_LOCAL_MODE)
59 rw: Use the local repo for reading and writing (if file permissions allow).
60 r-: Use the local repo for reading (if it exists and is readable).
61 --: Completely ignore the local repo, even if it exists.
62 * Repo.Local.Path (overrides HHVM_REPO_LOCAL_PATH)
63 Repo.Local.Path or HHVM_REPO_LOCAL_PATH can be used to specify where the local
64 repo is. If unspecified, then the local repo is 'path/to/cli.php.hhbc' in cli
65 mode or '<cwd>/hhvm.hhbc' in srv mode.
66 * Repo.Central.Path (overrides HHVM_REPO_CENTRAL_PATH)
67 There is always a central read-write repo. Non-eval units prefer to be written
68 in the local repo, but are written in the central repo if the local repo isn't
69 writeable. If unspecified, or unusable, will fall back first to
70 $HHVM_REPO_CENTRAL_PATH, and then to ~user/.hhvm.hhbc
71 * Repo.Central.FileMode
73 Repo.Central.FileGroup
74 Set the desired mode (as a bitmask), user, and/or group (as a user/group
75 name) for the file containing the central repo. Note that this is at the
76 filesystem level, as opposed to the Repo.Local.Mode setting, which is at the
79 The desired options, if set, will be applied immediately after successfully
80 opening the central repo. Success depends on the permissions of the hhvm
81 process and the current mode/owner of the repo file.
82 * Repo.AllowFallbackPath: true(*) or false
83 If false, do not attempt to open a local or central repo at paths other than
84 those explicitly specified by the Repo.Local.Path, HHVM_REPO_LOCAL_PATH,
85 Repo.Central.Path, or HHVM_REPO_CENTRAL_PATH options.
86 * Repo.Journal: delete(*) or memory
87 delete: Delete the on-disk SQLite journal upon each successful transaction
89 memory: Store the SQLite journal in memory. The hphp compiler uses this mode
90 when compiling because it is faster than delete mode (and safe under
91 such conditions), but it is unsafe to use under normal operating
93 * Repo.Commit: true(*) or false
94 If true, commit newly emitted units to the repo.
95 * Repo.DebugInfo: true(*) or false
96 If true, store full source locations; otherwise store only line
98 * Repo.Authoritative: false(*) or true
99 If true, use Repo as authoritative source for unit bytecode, do
100 not consult filesystem to check for existence of file or parse it.
101 Otherwise, fall back to parsing file from filesystem if unit
102 is not found in Repo.
103 * The environment variable $HHVM_RUNTIME_REPO_SCHEMA will override the schema