aboutsummaryrefslogtreecommitdiffstats
path: root/README.dev
diff options
context:
space:
mode:
Diffstat (limited to 'README.dev')
-rw-r--r--README.dev90
1 files changed, 0 insertions, 90 deletions
diff --git a/README.dev b/README.dev
deleted file mode 100644
index dbb97b0..0000000
--- a/README.dev
+++ /dev/null
@@ -1,90 +0,0 @@
-Extending BE
-============
-
-To write a plugin, you simply create a new file in the becommands
-directory. Take a look at one of the simpler plugins (e.g. open.py)
-for an example of how that looks, and to start getting a feel for the
-libbe interface.
-
-To fit into the current framework, your extension module should
-provide the following elements:
- __desc__
- A short string describing the purpose of your plugin
- execute(args, manipulate_encodings=True, restrict_file_access=False,
- dir=".")
- The entry function for your plugin. args is everything from
- sys.argv after the name of your plugin (e.g. for the command
- `be open abc', args=['abc']).
-
- manipulate_encodings should be passed through to any calls to
- bugdir.BugDir(). See the BugDir documentation for details.
-
- If restrict_file_access==True, you should call
- cmdutil.restrict_file_access(bugdir, path)
- before attempting to read or write a file. See the
- restrict_file_access documentation for details.
-
- dir is a directory inside the repository of interest.
-
- Note: be supports command-completion. To avoid raising errors you
- need to deal with possible '--complete' options and arguments.
- See the 'Command completion' section below for more information.
- help()
- Return the string to be output by `be help <yourplugin>',
- `be <yourplugin> --help', etc.
-
-While that's all that's strictly necessary, many plugins (all the
-current ones) use libbe.cmdutil.CmdOptionParser to provide a
-consistent interface
- get_parser()
- Return an instance of CmdOptionParser("<usage string>"). You can
- alter the parser (e.g. add some more options) before returning it.
-
-Again, you can just browse around in becommands to get a feel for things.
-
-
-Testing
--------
-
-Run any doctests in your plugin with
- be$ python test.py <yourplugin>
-for example
- be$ python test.py merge
-
-
-Command completion
-------------------
-
-BE implements a general framework to make it easy to support command
-completion for arbitrary plugins. In order to support this system,
-all becommands should properly handle the '--complete' commandline
-argument, returning a list of possible completions. For example
- $ be --commands
- lists options accepted by be and the names of all available becommands.
- $ be list --commands
- lists options accepted by becommand/list
- $ be list --status --commands
- lists arguments accepted by the becommand/list --status option
- $ be show -- --commands
- lists possible vals for the first positional argument of becommand/show
-This is a lot of information, but command-line completion is really
-convenient for the user. See becommand/list.py and becommand/show.py
-for example implementations. The basic idea is to raise
- cmdutil.GetCompletions(['list','of','possible','completions'])
-once you've determined what that list should be.
-
-However, command completion is not critical. The first priority is to
-implement the target functionality, with fancy shell sugar coming
-later. In recognition of this, cmdutil provides the default_complete
-function which ensures that if '--complete' is any one of the
-arguments, options, or option-arguments, GetCompletions will be raised
-with and empty list.
-
-Profiling
-=========
-
-Find out which 20 calls take the most cumulative time (time of
-execution + childrens' times).
-
- $ python -m cProfile -o profile be [command] [args]
- $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)"