This directory contains scripts for setting up and managing a cog-based workspace for Fuchsia development. Cog (Code on Git) is a system that allows developers to work with Git-on-Borg repositories using a virtual filesystem.
The primary script in this directory is setup-cog-workspace.
setup-cog-workspaceThis script initializes a new cog workspace. It is currently highly experimental and not recommended for general use.
This script has a custom shebang which prevents it from creating bytecode and creating pycache directories. This is needed because the pycache directories will not be ignored by the VCS.
To use this script, you must first set the FUCHSIA_ALLOW_SETUP_COG_WORKSPACE environment variable to acknowledge its experimental nature:
export FUCHSIA_ALLOW_SETUP_COG_WORKSPACE=1
Then, you can run the script from within your cog workspace directory. The script will automatically detect the workspace root based on the current directory, which must match the pattern /google/cog/cloud/<user>/<workspace_name>.
Example:
cd /google/cog/cloud/my-user/fuchsia-cog scripts/cog/setup_cog_workspace.py
In the near future, we expect to automatically run this script when cog activates the workspace. In order to prevent this from happening for users who are not actively working on making the script production ready, we require the FUCHSIA_ALLOW_SETUP_COG_WORKSPACE environment variable to be set.
To run the tests for this script, run the following command:
fx add-host-test //scripts/cog:tests
You can then run the tests with:
fx test
fx?This script must be run before we can use fx because it sets up jiri_root which is used by fx to find the Fuchsia source tree. Eventually, this script might be integrated into fx but at this time it must be run separately.
To ensure that a Cog workspace is correctly linked to its persistent storage in Cartfs, we use a unique workspace_id. This ID is sourced from .citc/workspace_id within the Cog workspace.
When a workspace is linked to a Cartfs directory, a .cog.json metadata file is created in that directory. This file contains:
workspace_name: The name of the Cog workspace.repo_name: The name of the repository (e.g., fuchsia).workspace_id: The unique ID for the workspace instance.The workspace_id is used to validate the link. If you attempt to use a previously existing Cartfs directory with the same workspace name but a different workspace_id, the script will consider the link invalid and suggest creating a new directory.
When this script runs, it will create (or link to) a directory in the Cartfs mount point. The suggested directory name is <workspace_name>-<workspace_id>.
Inside the Cartfs directory:
.cog.json: Metadata for linking validation.fuchsia: The fuchsia source directory.fuchsia/prebuilt/: A subdirectory for persistent prebuilts.integration: The integration repository..integration_commit_hash: The last known integration hash.out/: A subdirectory for build artifacts.The Cog workspace then points to these directories via symlinks (e.g., cartfs-dir symlink in the workspace root).