X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=HACKING;h=1121deb362f2a3b3f4fa0f32be202724c1a12f27;hp=fc9ed382ff442559c86aec35e9f7d4df1746ac7a;hb=4c5038ab54fb6fdff75ca8d5fdda9e73f48a5050;hpb=dcd8742578a57e0871d6db4797014bbfd854a57b diff --git a/HACKING b/HACKING index fc9ed38..1121deb 100644 --- a/HACKING +++ b/HACKING @@ -7,17 +7,13 @@ Adding a new action All action functions are generated automatically, so there are only two files you need to edit: -(1) src/generator.ml: Add your new action, parameters, description, -etc. to the big list called 'functions' at the top of this file. +(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. -You will need to run src/generator.ml (from the top directory) which -regenerates all the auto-generated files, and then continue with the -ordinary build process. - Formatting ---------------------------------------------------------------------- @@ -28,66 +24,186 @@ 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. + The qemu appliance, build scripts and so on. capitests/ - Automated tests of the C API. + 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. + Outside contributions, experimental parts. + +csharp/ + Experimental C# bindings. daemon/ - The daemon that runs inside the guest and carries out actions. + The daemon that runs inside the guest and carries out actions. + +df/ + 'virt-df' command and documentation. examples/ - The examples. + The examples. fish/ - Guestfish (the command-line program / shell) + 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. + 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. + 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. + Also contains some files used by the test suite. inspector/ - Virtual machine image inspector (virt-inspector). + Virtual machine image inspector (virt-inspector). java/ - Java bindings. + Java bindings. m4/ - M4 macros used by autoconf. + M4 macros used by autoconf. ocaml/ - OCaml bindings. + OCaml bindings. + +php/ + PHP bindings. po/ - Translations. + 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. + Perl bindings. python/ - Python bindings. + Python bindings. regressions/ - Regression tests. + Regression tests. + +rescue/ + 'virt-rescue' command and documentation. ruby/ - Ruby bindings. + Ruby bindings. + +tools/ + Command line tools written in Perl (virt-resize and more). src/ - Source code to the C library. - Also contains the crucial generator program. + 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 ---------------------------------------------------------------------- @@ -101,8 +217,8 @@ they will show up if you use 'guestfish -v'. Patches ---------------------------------------------------------------------- -Submit patches to the fedora-virt mailing list: -http://www.redhat.com/mailman/listinfo/fedora-virt +Submit patches to the mailing list: +http://www.redhat.com/mailman/listinfo/libguestfs and CC to rjones@redhat.com I18N @@ -118,3 +234,25 @@ 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.