X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=HACKING;fp=HACKING;h=c1888dfe2b311559b006cbda3abf5e8928c6c391;hp=1121deb362f2a3b3f4fa0f32be202724c1a12f27;hb=d2400da92e5e2cc7fd5e33e61220a33214d5241c;hpb=84fbe21855b5b304413075fecb444135397591e6 diff --git a/HACKING b/HACKING index 1121deb..c1888df 100644 --- a/HACKING +++ b/HACKING @@ -1,258 +1,2 @@ -PLEASE LOOK AT THE TOP OF EACH FILE BEFORE EDITING TO SEE WHETHER IT -IS AUTOMATICALLY GENERATED OR NOT. - -Adding a new action ----------------------------------------------------------------------- - -All action functions are generated automatically, so there are only -two files you need to edit: - -(1) generator/generator_actions.ml: Add your new action, parameters, -description, etc. to the big list at the top of this file. - -(2) Edit/create a C file in daemon/ subdirectory which implements your -'do_action' function. Take a look at one of the numerous examples -there. - -Formatting ----------------------------------------------------------------------- - -Try to use GNU / Emacs default formatting, following the convention -used elsewhere in the source. - -Please make sure that the code compiles without warnings. - -Please test any changes. - -Useful targets: - make syntax-check Checks the syntax of the C code. - make check Runs the test suite. - -Enable warnings, and fix any you find: - ./configure --enable-gcc-warnings - -Code indentation ----------------------------------------------------------------------- -Our C source code generally adheres to some basic code-formatting -conventions. The existing code base is not totally consistent on this -front, but we do prefer that contributed code be formatted similarly. -In short, use spaces-not-TABs for indentation, use 2 spaces for each -indentation level, and other than that, follow the K&R style. - -If you use Emacs, add the following to one of one of your start-up files -(e.g., ~/.emacs), to help ensure that you get indentation right: - - ;;; In libguestfs, indent with spaces everywhere (not TABs). - ;;; Exceptions: Makefile and ChangeLog modes. - (add-hook 'find-file-hook - '(lambda () (if (and buffer-file-name - (string-match "/libguestfs\\>" (buffer-file-name)) - (not (string-equal mode-name "Change Log")) - (not (string-equal mode-name "Makefile"))) - (setq indent-tabs-mode nil)))) - - ;;; When editing C sources in libguestfs, use this style. - (defun libguestfs-c-mode () - "C mode with adjusted defaults for use with libguestfs." - (interactive) - (c-set-style "K&R") - (setq c-indent-level 2) - (setq c-basic-offset 2)) - (add-hook 'c-mode-hook - '(lambda () (if (string-match "/libguestfs\\>" (buffer-file-name)) - (libguestfs-c-mode)))) - -Directories ----------------------------------------------------------------------- - -appliance/ - The qemu appliance, build scripts and so on. - -capitests/ - Automated tests of the C API. See "Tests" below. - -cat/ - The 'virt-cat', 'virt-filesystems' and 'virt-ls' commands and - documentation. - -contrib/ - Outside contributions, experimental parts. - -csharp/ - Experimental C# bindings. - -daemon/ - The daemon that runs inside the guest and carries out actions. - -df/ - 'virt-df' command and documentation. - -examples/ - The examples. - -fish/ - Guestfish (the command-line program / shell) - -fuse/ - FUSE (userspace filesystem) built on top of libguestfs. - -generator/ - The crucially important generator, used to automatically - generate large amounts of boilerplate C code for things like - RPC and bindings. - -haskell/ - Haskell bindings. - -hivex/ [removed in 1.0.85] - This used to contain the hivex library for reading and - writing Windows Registry binary hive files. This is now - available as a separate upstream project. - -images/ - Some guest images to test against. These are gzipped to save - space. You have to unzip them before use. - - Also contains some files used by the test suite. - -inspector/ - Virtual machine image inspector (virt-inspector). - -java/ - Java bindings. - -m4/ - M4 macros used by autoconf. - -ocaml/ - OCaml bindings. - -php/ - PHP bindings. - -po/ - Translations of simple gettext strings. For translations of - longer documents, see po-docs/. - -po-docs/ - The build infrastructure and PO files for translations of - manpages and POD files. Eventually this will be combined - with the po/ directory, but that is rather complicated. - -perl/ - Perl bindings. - -python/ - Python bindings. - -regressions/ - Regression tests. - -rescue/ - 'virt-rescue' command and documentation. - -ruby/ - Ruby bindings. - -tools/ - Command line tools written in Perl (virt-resize and more). - -src/ - Source code to the C library. - -test-tool/ - Interactive qemu/kernel test tool. - -Tests ----------------------------------------------------------------------- - -You can supply zero or as many tests as you want per API call. - -The test environment has 4 block devices: - /dev/sda 500MB General block device for testing. - /dev/sdb 50MB /dev/sdb1 is an ext2 filesystem used for testing - filesystem write operations. - /dev/sdc 10MB Used in a few tests where 2 block devices are needed. - /dev/sdd - ISO with fixed content (see images/test.iso). - -To be able to run the tests in a reasonable amount of time, the -virtual machine and block devices are reused between tests. So don't -try testing kill_subprocess :-x Between each test we blockdev-setrw, -umount-all, lvm-remove-all. - -Each test starts with an initial scenario, selected using one of the -'Init*' expressions, described in generator/generator_types.ml. These -initialize the disks in a particular way as described. You should not -assume anything about the previous contents of other disks that are -not initialized. - -You can add a prerequisite clause to any individual test. This is a -run-time check, which, if it fails, causes the test to be skipped. -Useful if testing a command which might not work on all variations of -libguestfs builds. A test that has prerequisite of 'Always' is run -unconditionally. - -In addition, packagers can skip individual tests by setting the -environment variables: eg: - - SKIP_TEST__=1 SKIP_TEST_COMMAND_3=1 (skips test #3 of command) - SKIP_TEST_=1 SKIP_TEST_ZEROFREE=1 (skips all zerofree tests) - -and packagers can run only certain tests by setting eg: - - TEST_ONLY="vfs_type zerofree" - -See capitests/tests.c for more details of how these environment -variables work. - -Debugging ----------------------------------------------------------------------- - -It's a good idea to use guestfish to try out new commands. - -Debugging the daemon is a problem because it runs inside a minimal -qemu environment. However you can print messages from the daemon, and -they will show up if you use 'guestfish -v'. - -Patches ----------------------------------------------------------------------- - -Submit patches to the mailing list: -http://www.redhat.com/mailman/listinfo/libguestfs -and CC to rjones@redhat.com - -I18N ----------------------------------------------------------------------- - -We support i18n (gettext anyhow) in the library. - -However many messages come from the daemon, and we don't translate -those at the moment. One reason is that the appliance generally has -all locale files removed from it, because they take up a lot of space. -So we'd have to readd some of those, as well as copying our PO files -into the appliance. - -Debugging messages are never translated, since they are intended for -the programmers. - -Extended printf ----------------------------------------------------------------------- - -In the daemon code we have created custom printf formatters %Q and %R, -which are used to do shell quoting. - -%Q => Simple shell quoted string. Any spaces or other shell characters - are escaped for you. - -%R => Same as %Q except the string is treated as a path which is prefixed - by the sysroot. - -eg. - -asprintf (&cmd, "cat %R", path); -==> "cat /sysroot/some\ path\ with\ spaces" - -Note: Do NOT use these when you are passing parameters to the -command{,r,v,rv}() functions. These parameters do NOT need to be -quoted because they are not passed via the shell (instead, straight to -exec). You probably want to use the sysroot_path() function however. +The contents of this page have moved to the section "EXTENDING LIBGUESTFS" +in the guestfs(3) man page.