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, bc_meta 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 writable, 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   writable. If unspecified, or unusable, will fall back first to
  70   $HHVM_REPO_CENTRAL_PATH, and then to ~user/.hhvm.hhbc
  71 * Repo.Eval.Mode: local, central, or readonly(*)
  72   local: Write eval units to the local repo if it is writable; otherwise write
  73          to the central repo.
  74   central: Write eval units to the central repo.
  75   readonly: Do not write eval units to a repo, but still search for them in
  76             repos.
  77 * Repo.Journal: delete(*) or memory
  78   delete: Delete the on-disk SQLite journal upon each successful transaction
  79           commit.
  80   memory: Store the SQLite journal in memory. The hphp compiler uses this mode
  81           when compiling because it is faster than delete mode (and safe under
  82           such conditions), but it is unsafe to use under normal operating
  83           conditions.
  84 * Repo.Commit: true(*) or false
  85   If true, commit newly emitted units to the repo.
  86 * Repo.DebugInfo: true(*) or false
  87   If true, store full source locations; otherwise store only line
  88   numbers.
  89 * Repo.Authoritative: false(*) or true
  90   If true, use Repo as authoritative source for unit bytecode, do
  91   not consult filesystem to check for existence of file or parse it.
  92   Otherwise, fall back to parsing file from filesystem if unit
  93   is not found in Repo.
  94 * The environment variable $HHVM_RUNTIME_REPO_SCHEMA will override the schema
  95   id.