hphp/doc/repo

   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
   6 hhvm.hhbc:
   7
   8   $ sqlite3 hhvm.hhbc '.schema'
   9
  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":
  17
  18   $ sqlite3 hhvm.hhbc '.dump magic_77fae842fab099b2eb4771f620e15a4bbf3883aa'
  19   PRAGMA foreign_keys=OFF;
  20   BEGIN TRANSACTION;
  21   CREATE TABLE magic_77fae842fab099b2eb4771f620e15a4bbf3883aa(product TEXT);
  22   INSERT INTO "magic_77fae842fab099b2eb4771f620e15a4bbf3883aa"
  23     VALUES('facebook.com HipHop Virtual Machine bytecode repository');
  24   COMMIT;
  25
  26 This table is used as a sanity check to assure that the repo is initialized to
  27 support the schema.
  28
  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.
  34
  35   $ sqlite3 hhvm.hhbc '.dump Unit_77fae842fab099b2eb4771f620e15a4bbf3883aa'
  36   PRAGMA foreign_keys=OFF;
  37   BEGIN TRANSACTION;
  38   CREATE TABLE Unit_77fae842fab099b2eb4771f620e15a4bbf3883aa(
  39     unitSn INTEGER PRIMARY KEY, md5 BLOB, bc BLOB,
  40     mainReturn BLOB, mergeable INTEGER,lines BLOB, UNIQUE (md5));
  41   COMMIT;
  42
  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
  45 are stored:
  46
  47   $ sqlite3 hhvm.hhbc 'SELECT COUNT(*)
  48                        FROM Unit_77fae842fab099b2eb4771f620e15a4bbf3883aa;'
  49   19452
  50
  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:
  57
  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
  72   Repo.Central.FileUser
  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
  77   sqlite level.
  78
  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.Eval.Mode: local, central, or readonly(*)
  87   local: Write eval units to the local repo if it is writeable; otherwise write
  88          to the central repo.
  89   central: Write eval units to the central repo.
  90   readonly: Do not write eval units to a repo, but still search for them in
  91             repos.
  92 * Repo.Journal: delete(*) or memory
  93   delete: Delete the on-disk SQLite journal upon each successful transaction
  94           commit.
  95   memory: Store the SQLite journal in memory. The hphp compiler uses this mode
  96           when compiling because it is faster than delete mode (and safe under
  97           such conditions), but it is unsafe to use under normal operating
  98           conditions.
  99 * Repo.Commit: true(*) or false
 100   If true, commit newly emitted units to the repo.
 101 * Repo.DebugInfo: true(*) or false
 102   If true, store full source locations; otherwise store only line
 103   numbers.
 104 * Repo.Authoritative: false(*) or true
 105   If true, use Repo as authoritative source for unit bytecode, do
 106   not consult filesystem to check for existence of file or parse it.
 107   Otherwise, fall back to parsing file from filesystem if unit
 108   is not found in Repo.
 109 * The environment variable $HHVM_RUNTIME_REPO_SCHEMA will override the schema
 110   id.