Changes between Version 61 and Version 62 of Building/GettingTheSources


Ignore:
Timestamp:
May 23, 2011 2:26:22 PM (3 years ago)
Author:
dmp
Comment:

Added info about the fingerprint.py script (Tracking full repository state)

Legend:

Unmodified
Added
Removed
Modified
  • Building/GettingTheSources

    v61 v62  
    5353 
    5454The [wiki:Building/SyncAll sync-all] script makes it easy to pull new patches.  For example, `sync-all pull` will pull all new patches from the original repository into the repository tree in the current directory. 
     55 
     56== Tracking the full repository state == 
     57 
     58The full state of a GHC repository includes the current state of the repositories for all of the GHC boot libraries that are used to to build GHC (see [wiki:Repositories] for a list of the boot libraries). The repositories for these libraries are fetched and updated by the `sync-all` script. To recored the full repository state (including boot libraries), git submodules could be used, but they are not currently in favor (see [wiki:DarcsConversion#Theperspectiveonsubmodules The perspective on submodules] for some reasons why). 
     59 
     60As an alternative to git submodules, the `fingerprint.py` script in `utils/fingerprint` can create a "fingerprint" to uniquely identify a GHC repository state by recording the current commits of the GHC and boot library repositories. This fingerprint can be used later to restore the state of all repositories to the state captured by the fingerprint.  
     61 
     62A fingerprint is created by parsing the output of the `sync-all` command: `./sync-all log HEAD^.. --pretty=oneline`. This command will list each repository along with its commit hash. The fingerprint can be saved for later use. Alternatively, the fingerprint can be created from a [wiki:Builder] log that includes the output of the `sync-all` command above. 
     63 
     64To create a new fingerprint, run the `create` command in the top level ghc repo. The fingerprint can also be created from a [wiki:Builder] log that contains the appropriate output from the `sync-all` command by passing the log file to the create command with the `-l` flag. 
     65 
     66{{{ 
     67$ ./utils/fingerprint.py create 
     68$ ./utils/fingerprint.py create -l builder.log 
     69}}} 
     70 
     71This command will create a new fingerprint, which is just pairs of repositories and commits.  
     72 
     73To restore a fingerprint use the `restore` command and pass either a fingerprint file with the `-f` flag or a builder log file with the `-l` flag. 
     74 
     75{{{ 
     76$ ./utils/fingerprint.py restore -f 2011-05-23.fp 
     77$ ./utils/fingerprint.py restore -l builder.log 
     78}}} 
     79 
     80This command will read the fingerprint and perform a checkout of the appropriate commit for each repository found in the fingerprint. By default, the `restore` command will create a new branch in the top level ghc repository and add an entry to git config that sets the new branch's remote to `origin`. The config options are added so that future `sync-all` commands will work as expected. Passing the `-n` flag will cause the fingerprint script not to create a new branch. To "unrestore" a fingerprint, simply use `sync-all` to checkout the `master` branch in each repository 
     81 
     82{{{ 
     83$ ./syncall checkout master 
     84}}} 
     85 
     86To make the best use of fingerprinting, you need to collect fingerprints for the states you may wish to restore. To ease the automatic collection of fingerprints, the `fingerprint.py` script allows a `-d DIR` option that will output a fingerprint to the directory `DIR` with the current time stamp as a file name. The `-g DIR` option tells the script to run in the ghc repository pointed to by `DIR`. These options can be useful for collecting fingerprints as a cron job or on a post-commit hook.