diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 91 |
1 files changed, 91 insertions, 0 deletions
@@ -0,0 +1,91 @@ +Here are some hints and tips or working on src:dgit +=================================================== + +Program and source code layout +------------------------------ + +Most stuff is in the toplevel. +Debian/ contains Perl modules, notably Debian/Dgit.pm. +That module contains much shared code and is used by every package. + +The test suite is very useful for ad-hoc work, so see "Tests" below. + +Coding style +------------ + +I like to use perl "poetry mode" where ( ) are often elided. +This is often nice and terse but there is a gotcha. This + some_function ($a + 2), $b, $c +is wrong, because the ( ) are treated as function call ( ) +for some_function. When this is a risk, you have to write: + some_function +($a + 2), $b, $c + +Keep the line length to 75 at most please. + +i18n +---- + +In the Perl code we use these functions: + + here: meaning: like, in C: + __ translate this message _ aka gettext + f_ this is a sprintf string to be translated sprintf(_ ... + i_ mark for translation but do not translate here gettext_noop + +See the info node `(gettext) Sources' for the complete semantics. + +The shell scripts are not translated right now. + +Running ad-hoc +-------------- + +You can run everything right out of the git tree, for ad hoc testing,, +like this (supposing your dgit tree is in things/Dgit/dgit): + + ~/things/Dgit/dgit/using-these dgit --some-option blah blah + +using-these will set PATH and PERLLIB so that programs and modules +come from its own directory (obtained from $0). + +Tests, running and use for hacking +---------------------------------- + +The test cases are in bash and are in tests/tests/*. They all use +shell libraries tests/lib*. + +You can run it formally with autopkgtest, but you normally want to run +tests in one of these two ways [1]: + + tests/using-intree tests/tests/<some-test> 2>&1 |tee ../log + tests/run-all [tests/tests/<some shell glob>] + +These will leave their working stuff in ./tests/tmp/<name-of-test>. + +The test suite is often a nice way to set up situations for ad-hoc +testing. You can add "xxx" in the middle of one of the test cases to +get it to crash at the right point. Have an absolute cd like + cd ~/things/Dgit/dgit/tests/tmp/<some-test> +in your shell history, because each time you run the test it will +blow that directory away again. + +There are many env vars settings like + DGIT_TEST_DEBUG= DGIT_TEST_DEBUG=-DDD + DGIT_TEST_DEBPUSH_DEBUG= DGIT_TEST_DEBPUSH_DEBUG=x +which can be used to control the level of debug output from +individual programs run by the test suite. + +Editing/adding tests +-------------------- + +Things in tests/setup/ generate canned starting points. You can run +them by hand, but when they are imported by other tests they are not +automatically regenerated by default. So if you are editing one of +those, git-clean is your friend. + +debian/tests/control is autogenerated by a rule in debia/rules. If +making actual releases, you must rerun that. + +[1] The test suite and libraries, when run without any special +environment variables, expect to be run via DEP-8 (autopkgtest) - so +they want an to everything out of PATH and /usr. But there are also +arrangements to honour environment variables set by using-intree. |