X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=generator%2Fgenerator_types.ml;h=369a49a3e91397673ad92398c3a84e1414179dd7;hb=2860b21ee1b86d6c944308a8be181c91bc07fd03;hp=49d37922c7976b22f3c14ec3251f03fc6a306fe6;hpb=b42262c3db6013c363e2532cf7a466ccaf4d49f0;p=libguestfs.git diff --git a/generator/generator_types.ml b/generator/generator_types.ml index 49d3792..369a49a 100644 --- a/generator/generator_types.ml +++ b/generator/generator_types.ml @@ -20,7 +20,45 @@ (* Types used to describe the API. *) -type style = ret * args +type style = ret * args * args + (* The [style] is a tuple which describes the return value and + * arguments of a function. + * + * [ret] is the return value, one of the [R*] values below. + * + * The second element is the list of required arguments, a list of + * [argt]s from the list below, eg. [Bool], [String] etc. Each has + * a name so that for example [Int "foo"] corresponds in the C + * bindings to an [int foo] parameter. + * + * The third element is the list of optional arguments. These are + * mapped to optional arguments in the language binding, eg. in + * Perl to: + * $g->fn (required1, required2, opt1 => val, opt2 => val); + * As the name suggests these are optional, and the function can + * tell which optional parameters were supplied by the caller. + * + * Only [Bool], [Int], [Int64], [String] may currently appear in + * the optional argument list (we may permit more types in future). + * + * ABI and API considerations + * -------------------------- + * + * The return type and required arguments may not be changed after + * these have been published in a stable version of libguestfs, + * because doing so would break the ABI. + * + * If a published function has one or more optional arguments, + * then the call can be extended without breaking the ABI or API. + * This is in fact the only way to change an existing function. + * There are limitations on this: + * + * (1) you may _only_ add extra elements at the end of the list + * (2) you may _not_ rearrange or rename or remove existing elements + * (3) you may _not_ add optional arguments to a function which did + * not have any before (since this breaks the C ABI). + *) + and ret = (* "RErr" as a return value means an int used as a simple error * indication, ie. 0 or -1. @@ -108,14 +146,10 @@ and ret = and args = argt list (* Function parameters, guestfs handle is implicit. *) - (* Note in future we should allow a "variable args" parameter as - * the final parameter, to allow commands like - * chmod mode file [file(s)...] - * This is not implemented yet, but many commands (such as chmod) - * are currently defined with the argument order keeping this future - * possibility in mind. - *) and argt = + | Bool of string (* boolean *) + | Int of string (* int (smallish ints, signed, <= 31 bits) *) + | Int64 of string (* any 64 bit int *) | String of string (* const char *name, cannot be NULL *) | Device of string (* /dev device name, cannot be NULL *) | Pathname of string (* file name, cannot be NULL *) @@ -123,19 +157,6 @@ and argt = | OptString of string (* const char *name, may be NULL *) | StringList of string(* list of strings (each string cannot be NULL) *) | DeviceList of string(* list of Device names (each cannot be NULL) *) - | Bool of string (* boolean *) - | Int of string (* int (smallish ints, signed, <= 31 bits) *) - | Int64 of string (* any 64 bit int *) - (* These are treated as filenames (simple string parameters) in - * the C API and bindings. But in the RPC protocol, we transfer - * the actual file content up to or down from the daemon. - * FileIn: local machine -> daemon (in request) - * FileOut: daemon -> local machine (in reply) - * In guestfish (only), the special name "-" means read from - * stdin or write to stdout. - *) - | FileIn of string - | FileOut of string (* Opaque buffer which can contain arbitrary 8 bit data. * In the C API, this is expressed as pair. * Most other languages have a string type which can contain @@ -154,6 +175,33 @@ and argt = * from the user. *) | Key of string + (* These are treated as filenames (simple string parameters) in + * the C API and bindings. But in the RPC protocol, we transfer + * the actual file content up to or down from the daemon. + * FileIn: local machine -> daemon (in request) + * FileOut: daemon -> local machine (in reply) + * In guestfish (only), the special name "-" means read from + * stdin or write to stdout. + *) + | FileIn of string + | FileOut of string + (* This specifies an opaque pointer that is passed through + * untouched. Only non-daemon functions are supported. + * + * Pointer ("foo *", "bar") translates to "foo *bar" in the + * C API. The pointer ("bar") cannot be NULL. + * + * This is less well supported in other language bindings: + * if the pointer type is known then we may be able to produce + * a suitable binding, otherwise this is translated into a 64 + * bit int. + * + * Functions with this parameter type are not supported at all + * in guestfish (the function must be declared "NotInFish" else + * you will get an error). Also the function cannot contain + * tests, although we should fix this in future. + *) + | Pointer of (string * string) type flags = | ProtocolLimitWarning (* display warning about protocol size limits *) @@ -170,38 +218,7 @@ and fish_output_t = | FishOutputOctal (* for int return, print in octal *) | FishOutputHexadecimal (* for int return, print in hex *) -(* You can supply zero or as many tests as you want per API call. - * - * Note that the test environment has 3 block devices, of size 500MB, - * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and - * a fourth ISO block device with some known files on it (/dev/sdd). - * - * Note for partitioning purposes, the 500MB device has 1015 cylinders. - * Number of cylinders was 63 for IDE emulated disks with precisely - * the same size. How exactly this is calculated is a mystery. - * - * The ISO block device (/dev/sdd) comes from 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. - * - * Don't assume anything about the previous contents of the block - * devices. Use 'Init*' to create some initial scenarios. - * - * 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) - *) +(* See section "Tests" in HACKING file. *) type tests = (test_init * test_prereq * test) list and test = (* Run the command sequence and just expect nothing to fail. *) @@ -266,6 +283,12 @@ and test = *) | TestOutputFileMD5 of seq * string + (* Run the command sequence and expect the output of the final + * command to be a string which is a block device name (we don't + * check the 5th character of the string, so "/dev/sda" == "/dev/vda"). + *) + | TestOutputDevice of seq * string + (* Run the command sequence and expect the final command (only) * to fail. *) @@ -311,15 +334,16 @@ and test_init = | InitEmpty (* /dev/sda contains a single partition /dev/sda1, with random - * content. /dev/sdb and /dev/sdc may have random content. - * No LVM. + * content. No LVM. *) | InitPartition (* /dev/sda contains a single partition /dev/sda1, which is formatted * as ext2, empty [except for lost+found] and mounted on /. - * /dev/sdb and /dev/sdc may have random content. * No LVM. + * + * Note: for testing filesystem operations, it is quicker to use + * InitScratchFS *) | InitBasicFS @@ -327,7 +351,9 @@ and test_init = * /dev/sda1 (is a PV): * /dev/VG/LV (size 8MB): * formatted as ext2, empty [except for lost+found], mounted on / - * /dev/sdb and /dev/sdc may have random content. + * + * Note: only use this if you really need a freshly created filesystem + * on LVM. Normally you should use InitScratchFS instead. *) | InitBasicFSonLVM @@ -336,6 +362,16 @@ and test_init = *) | InitISOFS + (* /dev/sdb1 (write scratch disk) is mounted on /. The filesystem + * will be empty. + * + * Note that this filesystem is not recreated between tests, and + * could contain random files and directories from previous tests. + * Therefore it is recommended that you create uniquely named files + * and directories for your tests. + *) + | InitScratchFS + (* Sequence of commands for testing. *) and seq = cmd list and cmd = string list