Difference between revisions of "Mercurial Tools"

From Second Life Wiki
Jump to navigation Jump to search
 
(3 intermediate revisions by 2 users not shown)
Line 9: Line 9:
'''You are strongly encouraged to check out a copy of this repository and install the coding policy script there as described below, since anything you submit must pass those checks.'''
'''You are strongly encouraged to check out a copy of this repository and install the coding policy script there as described below, since anything you submit must pass those checks.'''


== Coding Policy ==
__TOC__
 
The <tt>coding_policy.py</tt> file provides both a Mercurial command extension '''hg policy''' and a hook that you should install to check all files when they are committed.


{{Note|
{{Note|
Line 18: Line 16:
*For Mac and Linux: <code>$HOME/.hgrc</code>
*For Mac and Linux: <code>$HOME/.hgrc</code>


You should have created this file when you installed Mercurial and established your username (and, optionally, your email address).  If the file does not exist, create it.
You should have created this file when you installed Mercurial and established your username (and, optionally, your email address).  If the file does not exist, create it (see [[Creating a version control repository#Preparing_to_use_Mercurial]]).
}}
}}


== Commit Hook ==
== Coding Policy ==
 
The <tt>coding_policy.py</tt> file provides both a Mercurial command extension '''hg policy''' and a hook that you should install to check all files when they are committed.
 
=== Policy Commit Hook ===


All changes pulled to a Linden Lab repository will have to pass the checks enforced by the command above.  This is enforced when the changes are pulled by the hook provided by <tt>coding_policy.py</tt>.
All changes pulled to a Linden Lab repository will have to pass the checks enforced by the command above.  This is enforced when the changes are pulled by the hook provided by <tt>coding_policy.py</tt>.
Line 44: Line 46:
  pretxnchangegroup.coding_policy =
  pretxnchangegroup.coding_policy =


== <tt>hg policy</tt> command ==
=== <tt>hg policy</tt> command ===


To install the extension, add the following to your '''Mercurial Initialization File''' (changing ''/path/to'' to the location where you checked out the hg-tools repository):
To install the extension, add the following to your '''Mercurial Initialization File''' (changing ''/path/to'' to the location where you checked out the hg-tools repository):
Line 101: Line 103:
  pre-push.confirm = python:/path/to/confirm_target.py:hook
  pre-push.confirm = python:/path/to/confirm_target.py:hook


== <tt>hg create</tt> Command ==


The ''hg create'' command can be used to simplify the process of creating new C++ files, adding them to the repository, and including them in the appropriate cmake file lists. To install this command, add the following to your '''Mercurial Initialization File''' (changing ''/path/to'' to the location where you checked out the hg-tools repository):
== For TortoiseHg Users ==
If you use TortoiseHg and find errors such as this:


  [extensions]
  Checking Linden Lab proprietary coding policies...
  create = /path/to/create.py
  autobuild.xml: this hook requires llsd from the llbase python package
  (to skip this check, commit a trivial change to this file,
  and add the text "'warn-on-failure:valid-llsd'" to your commit comment)


This will automatically set up hooks for the commands ''hg add'', ''hg remove'', and ''hg addremove'' as well as provide access to the ''hg create'' command itself.
This is due to TortoiseHg using its own python system and not finding llbase.  See http://tortoisehg.readthedocs.io/en/latest/faq.html  To fix this, first ensure you actually have llbase installed:


There are a few main ways to use the command.
pip install llbase -U
#''hg create path/to/foo'' -- This will, at a minimum, create a pair of files ''foo.cpp'' and ''foo.h'' in ''path/to'' and add them to the repository. The new files will be created by populating the templates in ''<repo>/scripts/templates/'' or, if those files do not exist, in ''<hg-tools>/templates''
#''hg create path/to/foo.<cpp|h>'' -- This will create and add only a .h or .cpp file.


Use of the command's manifest features requires a few preparatory steps detailed below. If these are followed, then ''hg create'' (used alone or via the ''hg'' command hooks) will also attempt to create or regenerate a manifest file for use by CMake.
Then create a file 'setsyspath.py' with this simple python code that adds the path to installed llbase to the system path:


Suppose you have the following repo set-up:
import sys
sys.path.append(r'C:\Python27\Lib\site-packages')


repo-root/indra/llmath/
Save this somewhere on your system
repo-root/indra/llmath/CMakeLists.txt
repo-root/indra/llmath/somefile.cpp
repo-root/indra/llmath/somefile.h


And let's say you want to add a file ''repo-root/indra/llmath/other/file.cpp''. From inside the repo, you would run
Next, edit your global hg configuration file and add this as the first extension:


  hg create indra/llmath/other/file.cpp
  [extensions]
 
  00setSysPath = C:\<path to where you saved the file>\setsyspath.py
After creating the file and adding it to the repository, the script will search up the directory tree from ''file.cpp'' until it locates a directory containing a ''CmakeLists.txt'' file. If it does not find one, it will terminate with a message.
 
If a ''CMakeLists.txt'' file ''is'' found, it will be searched to ensure that it contains references to ''llmath_SOURCE_FILES'', ''llmath_HEADER_FILES'', and contains a line that reads ''include(manifest.cmake)''. This is done to ensure that a manifest is not generated if the library is not yet set up to use it.
 
Assuming that the ''CMakeLists.txt'' file has been set up to reference the manifest, the file
   
repo-root/indra/llmath/manifest.cmake
 
will be created. ''manifest.cmake'' is a CMake format file that defines three main things:
#llmath_SOURCE_FILES -- a list containing all .cpp files under the library directory but excluding any that fall under a directory named 'tests'
#llmath_HEADER_FILES -- a list containing all .h and .inl files under the library directory but excluding any that fall under a directory named 'tests'
#Several source_groups to defines folders in Visual Studio. These will group your library's source files under subfolders according to directory name.
 
To use ''hg create'' without rebuilding the manifest, use the
 
hg create -n path/to/file
 
option. To use ''only'' rebuild the manifest, use
 
hg create -r
 
from within the library directory.


[[User:Falcon Linden|Falcon Linden]] 14:50, 9 September 2011 (PDT)
This will add the path to the libraries installed on your normal python installation to hg's python code

Latest revision as of 13:47, 4 April 2017

The Mercurial repository

https://bitbucket.org/lindenlab/hg-tools

contains tools for working with Linden Lab repositories.

You are strongly encouraged to check out a copy of this repository and install the coding policy script there as described below, since anything you submit must pass those checks.

NOTE:

The Mercurial Initialization File referred to in the instructions below depends on your operating system. The path to it is

  • For Windows: %USERPROFILE%\Mercurial.ini
  • For Mac and Linux: $HOME/.hgrc

You should have created this file when you installed Mercurial and established your username (and, optionally, your email address). If the file does not exist, create it (see Creating a version control repository#Preparing_to_use_Mercurial).

Coding Policy

The coding_policy.py file provides both a Mercurial command extension hg policy and a hook that you should install to check all files when they are committed.

Policy Commit Hook

All changes pulled to a Linden Lab repository will have to pass the checks enforced by the command above. This is enforced when the changes are pulled by the hook provided by coding_policy.py.

To make that check automatic when you are doing local commits, add the following to your Mercurial Initialization File (changing /path/to to the location where you checked out the hg-tools repository):

[hooks]
pretxncommit.coding_policy = python:/path/to/coding_policy.py:hook

you can also check all changes you pull into your repository by adding this (also under [hooks]):

pretxnchangegroup.coding_policy = python:/path/to/coding_policy.py:hook

Anyone maintaining a shared repository is encouraged to install this so that you can prevent problems when you attempt to merge your shared repository back to viewer-development.

These hooks apply only to repositories that are related to (share a common ancestor with) specific Linden Lab repositories (see the repo_root variable assignment in the source). Operations on those repositories will print a message describing which policy is being applied, or one that indicates that the repository is not subject to Linden Lab policy checks.

You can exempt a specific repository by adding an empty hook assignment to it; this is useful for working on older repositories that don't contain all the fixes to make them pass:

[hooks]
pretxncommit.coding_policy = 
pretxnchangegroup.coding_policy =

hg policy command

To install the extension, add the following to your Mercurial Initialization File (changing /path/to to the location where you checked out the hg-tools repository):

[extensions]
policy = /path/to/coding_policy.py

To check changes against Linden Lab coding policy

 hg policy [-p {opensource|proprietary}] {[-f FILE] | [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]}

With no arguments, check uncommitted changes in the working directory.

A specific file (whether or not it has been added to the repository or modified) can be checked by using the -f/--file file option.

When revisions are specified via -r/--rev, check the given committed changes in the local repository.

When given a remote repository, check changes that have been committed locally that are not present in the remote repository. To check changes that would be pushed by default, specify "default-push" as the repository name.

KBwarning.png Warning: Specifying another repository currently does not work... I am working on it, but the hook function, checking changes in your local repository prior to commit, and checking a specific file do seem to be working.

As an alternative to the above - if you need to see whether or not the changes in your repo will pass the commit hook when pulled to some other repo, preview the operation by:

  1. Install the pretxnchangegroup hook as described above
  2. Make a clone of the destination repository
  3. Change to the destination clone
  4. Pull from your working repository

The pretxnchangegroup hook will then analyze all the pulled changes.

Oz Linden 04:02, 19 August 2011 (PDT)

The checks may be against either of two policy sets: opensource or proprietary options:

-p|--policy POLICY
The set of policies to check: POLICY may be either 'opensource' or 'proprietary' (the default depends on the repository)
-r|--rev REVISION
a revision up to which you would like to check (may be specified more than once for a range)
-f|--file FILE
a file to check (whether or not it has been modified)

Confirm Push Target Hook

The confirm_target.py hook can be used to protect yourself from accidentally pushing to sensitive repositories. It will prompt you for confirmation if you attempt to push into any repository whose name ends with one of:

/lindenlab/server-trunk
/lindenlab/viewer-development
/lindenlab/viewer-pre-beta
/lindenlab/viewer-beta
/lindenlab/viewer-pre-release
/lindenlab/viewer-release

To install, add the following to your Mercurial Initialization File (changing /path/to to the location where you checked out the hg-tools repository):

[hooks]
pre-push.confirm = python:/path/to/confirm_target.py:hook


For TortoiseHg Users

If you use TortoiseHg and find errors such as this:

Checking Linden Lab proprietary coding policies...
autobuild.xml: this hook requires llsd from the llbase python package
  (to skip this check, commit a trivial change to this file,
  and add the text "'warn-on-failure:valid-llsd'" to your commit comment)

This is due to TortoiseHg using its own python system and not finding llbase. See http://tortoisehg.readthedocs.io/en/latest/faq.html To fix this, first ensure you actually have llbase installed:

pip install llbase -U

Then create a file 'setsyspath.py' with this simple python code that adds the path to installed llbase to the system path:

import sys
sys.path.append(r'C:\Python27\Lib\site-packages')

Save this somewhere on your system

Next, edit your global hg configuration file and add this as the first extension:

[extensions]
00setSysPath = C:\<path to where you saved the file>\setsyspath.py

This will add the path to the libraries installed on your normal python installation to hg's python code