Update guides/hack from HHVM repository

Author: Wilfred

guides/hack/18-packages/01-introduction.md

@@ -1,27 +1,89 @@
-# Introduction
+# Introduction to Packages
 
-Packages are an extension to modules for HHVM and Hack which allows developers to more easily configure which files to build and deploy.
+Packages are a file-based mechanism for organizing code into logical units with explicit dependencies and fine-grained deployment control.
 
-## Package definitions
-A **package** is defined by a set of modules meant to be deployed together. Packages are configured in a toml file called `PACKAGES.toml` located at the root of your codebase (next to .hhconfig).
+## Key Concepts
+
+**Packages** group related files in your codebase (e.g., production code, test code, experimental features).
+
+**Deployments** define which packages to build and run together.
+
+**Package relationships:** Packages explicitly include other packages to access their symbols, creating a dependency graph.
+
+## Quick Example
+
+Packages are configured in a TOML file called `PACKAGES.toml` located at the root of your codebase (next to `.hhconfig`):
 
 ```toml PACKAGES.toml
 [packages]
 
 [packages.production]
-uses=["prod.*", "my_prod"] # Package contains all modules that start with `prod`, and the module "my_prod".
+include_paths = ["//flib/"]
 
 [packages.test]
-uses=["test.*"]
-includes=["production"] # Package depends on the production package
+include_paths = ["//flib/test/"]
+includes = ["production"]  # test depends on production
+
+[deployments]
+
+[deployments.production]
+packages = ["production"]
+
+[deployments.test]
+packages = ["test", "production"]  # must include dependencies
+```
+
+In this example:
+- The `production` package contains all files in `//flib/` (but not those in //flib/test/)
+- The `test` package contains files in `//flib/test/` and can access symbols defined in files in the production package
+- Two deployments are defined: one for production-only and one that includes tests
+
+## How Packages Work
+
+Each file in your codebase belongs to exactly one package. The same file path cannot appear in multiple packages' `include_paths` clauses.
+
+## File package membership
+
+Files can be assigned to packages in two ways:
+
+### 1. Via `include_paths` in PACKAGES.toml
+
+The `include_paths` clause specifies which files belong to a package:
+- Items are relative paths starting with `//` (representing the root directory)
+- A path ending with `/` (e.g., `"//flib/"`) includes all files recursively in that directory
+- A path without trailing `/` (e.g., `"//flib/foo.php"`) includes only that specific file
+
+### 2. Via `__PackageOverride` file attribute
+
+A file can override its package membership using the `__PackageOverride` attribute:
+
+```hack no-extract
+<?hh
+<<file: __PackageOverride('production')>>
+// This file now belongs to the 'production' package
 ```
 
-Every module can be in at most one package, so the same module cannot be part of two packages. Therefore, the same glob cannot appear in the uses clause of two different modules.
+## Precedence rules
+
+When determining which package a file belongs to:
+1. If a file has a `__PackageOverride` attribute, it belongs to that package
+2. Otherwise, if the full (relative-to-php-root) file path appears in an `include_paths` clause, it belongs to that package
+3. Otherwise, the file belongs to the package whose `include_paths` contains the file's nearest ancestor directory (i.e. the longest prefix match)
+4. If none of the above apply, the file belongs to the **default package**
+
+## Default package
+
+Any file not specified in any package (neither via `include_paths` nor `__PackageOverride`) belongs to the implicit "default" package. Symbols within the default package are not accessible from other packages. The default package:
+- Cannot be explicitly defined with the name "default" (the name is reserved)
+- Cannot be referenced via its name in `includes` and `soft_includes` lists
+- Can be made explicit by creating a package that includes `"//"`
+
+**Example of making default explicit:**
+```toml
+[packages.orphans]
+include_paths = ["//"]
+```
 
-## Overlaps in module globs
-- It is an error for the same module glob to appear in multiple package definitions.  Given a module with name foo.bar, we resolve what package the module belongs to with the following precedence:
-- If a package lists foo.bar directly in its use clause, foo.bar belongs to that package. If multiple packages list foo.bar directly, we throw an error at package definition.
-- If no package directly references the module, but a package has a prefix which matches foo.bar (in this case, foo.* for example), foo.bar belongs to the package with that prefix. If multiple packages list a prefix of the module, we take the most specific prefix, i.e. the longest prefix that matches.
-- If no package references the module in its use clause, the module belongs to the default package.
+This creates a package that captures all files not in other packages.
 
 Once you've defined a set of packages, you can deploy them using [deployments](/docs/hack/packages/deployments).

guides/hack/18-packages/02-deployments.md

@@ -1,36 +1,90 @@
 # Deployments
 
-Once you've defined a set of packages, you can deploy them using **deployments**.
+## What is a Deployment?
 
-## Deployments
-A **deployment** is defined as a set of packages. Deployments are also defined in PACKAGES.toml:
+A **deployment** is a set of packages built and deployed together. One may think of it as a build target configuration telling HHVM which code to compile and run.
+
+**Key requirements:**
+- A deployment must be **transitively closed** with respect to package dependencies
+- If package A includes package B, and A is deployed, B must also be explicitly deployed
+
+## Defining Deployments
+
+Deployments are defined in the `[deployments]` section of `PACKAGES.toml`:
 
 ```toml PACKAGES.toml
 [packages]
 
 [packages.production]
-uses=["prod.*", "my_prod"] # Package contains all modules that start with `prod`, and the module "my_prod".
+include_paths = ["//flib/"]
 
 [packages.test]
-uses=["test.*"]
-includes=["production"] # Package depends on the production package
+include_paths = ["//flib/test/"]
+includes = ["production"]
 
 [deployments]
+
 [deployments.production]
-packages=["production"]
+packages = ["production"]
 
 [deployments.test]
-packages=["test", "production"] # Since the test package includes production, they must be deployed together.
+packages = ["test", "production"]  # Must include production since test depends on it
+```
+
+### Transitive Closure Requirement
+
+The `packages` list must include all transitive dependencies:
+
+```toml
+[packages.core]
+include_paths = ["//flib/core/"]
+
+[packages.utils]
+include_paths = ["//flib/utils/"]
+includes = ["core"]
+
+[packages.app]
+include_paths = ["//flib/app/"]
+includes = ["utils"]
+
+[deployments.app]
+# Error: Missing core
+# packages = ["app", "utils"]
+
+# Correct: Includes all transitive dependencies
+packages = ["app", "utils", "core"]
+```
+
+Even though `app` only directly includes `utils`, the deployment must explicitly list all three packages.
+
+## Using Deployments with HHVM
+
+Specify the active deployment:
+
+```ini
+Eval.Runtime.ActiveDeployment = production
 ```
 
-When building in [repo authoritative](/docs/hack/../hhvm/advanced-usage/repo-authoritative) mode, you can pass in the build configuration `Eval.ActiveDeployment = <deployment>` to set the active deployment. HHVM will then include only the files in the active deployment when building.
+When running in [repo authoritative](/docs/hhvm/advanced-usage/repo-authoritative) mode, HHVM only compiles and runs files from packages in the specified deployment. References to undeployed packages cause runtime errors (e.g., "Class not found" or "Call to undefined function"). When running in other modes, the active deployment serves only to modify semantics of `package` checks and the `__RequirePackage` attribute.
 
-## Deployment domains
-In CLI-server mode, HHVM can direct different domains to different deployments, allowing you to treat a web request as if it were built in repo mode with a specific deployment. You can set the `domains` value of to any deployment to a list of regexes:
+
+### Force Symbol References (Legacy)
+
+For migration purposes, one can use the `ForceEnableSymbolRefs` option to allow additional "symbolically-referenced" files to be built alongside the active deployment. Note that this only affects [repo authoritative](/docs/hhvm/advanced-usage/repo-authoritative) mode.
+
+## Soft Packages (Migration Support)
+
+Deployments can specify `soft_packages` for files intended to be later excluded:
 
 ```toml
 [deployments.production]
-packages=["production"]
-domains=["^.*my_website\.com"]
+packages = ["production"]
+soft_packages = ["legacy_code"]
 ```
-The domains field matches on the `Host` field of any web request that HHVM serves. In this example, traffic that hits `my_website.com` will be treated as if the active deployment were production. Note that a hostname can match multiple regexes, but the **first** deployment listed which has a regex that matches the hostname will be used.
+
+Accessing soft-deployed package symbols logs a warning instead of throwing an error, allowing identification of dynamic boundary violations.
+
+**Rules:**
+- Soft-included packages must be at least soft-deployed
+- Hard-included packages must be hard-deployed
+- `package_exists()` returns `false` for soft packages. See [Cross Package Usage](/docs/hack/packages/cross-package-calls) for details.