There is precisely one such function at the moment (guestfs_wait_ready). --- generator/GObject.ml | 6 +- generator/OCaml.ml | 7 +- generator/actions_core_deprecated.ml | 102 ++++++++++++++--------------- generator/actions_inspection_deprecated.ml | 2 +- generator/actions_properties_deprecated.ml | 12 ++-- generator/c.ml | 27 +++++--- generator/checks.ml | 4 +- generator/docstrings.ml | 14 +++- generator/java.ml | 11 ++-- generator/ruby.ml | 9 ++- generator/types.ml | 9 ++- 11 files changed, 118 insertions(+), 85 deletions(-) diff --git a/generator/GObject.ml b/generator/GObject.ml index eada33c..fd2c07c 100644 --- a/generator/GObject.ml +++ b/generator/GObject.ml @@ -1118,9 +1118,11 @@ guestfs_session_close (GuestfsSession *session, GError **err) ); pr "\n"; (match deprecated_by with - | None -> () - | Some alt -> + | Not_deprecated -> () + | Replaced_by alt -> pr " * Deprecated: In new code, use guestfs_session_%s() instead\n" alt + | Deprecated_no_replacement -> + pr " * Deprecated\n" ); (match version_added f with | None -> () diff --git a/generator/OCaml.ml b/generator/OCaml.ml index 083e505..38b254d 100644 --- a/generator/OCaml.ml +++ b/generator/OCaml.ml @@ -186,10 +186,13 @@ end opt ); (match f.deprecated_by with - | None -> () - | Some replacement -> + | Not_deprecated -> () + | Replaced_by replacement -> has_tags := true; pr "\n\n @deprecated Use {!%s} instead" replacement + | Deprecated_no_replacement -> + has_tags := true; + pr "\n\n @deprecated" ); (match version_added f with | None -> () diff --git a/generator/actions_core_deprecated.ml b/generator/actions_core_deprecated.ml index b8cca79..ae93f29 100644 --- a/generator/actions_core_deprecated.ml +++ b/generator/actions_core_deprecated.ml @@ -28,7 +28,7 @@ let non_daemon_functions = [ name = "wait_ready"; added = (0, 0, 3); style = RErr, [], []; visibility = VStateTest; - deprecated_by = Some "launch"; + deprecated_by = Deprecated_no_replacement; blocking = false; shortdesc = "wait until the hypervisor launches (no op)"; longdesc = "\ @@ -46,7 +46,7 @@ versions of the API." }; { defaults with name = "kill_subprocess"; added = (0, 0, 3); style = RErr, [], []; - deprecated_by = Some "shutdown"; + deprecated_by = Replaced_by "shutdown"; shortdesc = "kill the hypervisor"; longdesc = "\ This kills the hypervisor. @@ -56,7 +56,7 @@ Do not call this. See: C<guestfs_shutdown> instead." }; { defaults with name = "add_cdrom"; added = (0, 0, 3); style = RErr, [String "filename"], []; - deprecated_by = Some "add_drive_ro"; config_only = true; + deprecated_by = Replaced_by "add_drive_ro"; config_only = true; blocking = false; shortdesc = "add a CD-ROM disk image to examine"; longdesc = "\ @@ -68,7 +68,7 @@ of C<guestfs_add_drive_ro>." }; { defaults with name = "add_drive_with_if"; added = (1, 0, 84); style = RErr, [String "filename"; String "iface"], []; - deprecated_by = Some "add_drive"; config_only = true; + deprecated_by = Replaced_by "add_drive"; config_only = true; blocking = false; shortdesc = "add a drive specifying the QEMU block emulation to use"; longdesc = "\ @@ -79,7 +79,7 @@ to specify the QEMU interface emulation to use at run time." }; name = "add_drive_ro_with_if"; added = (1, 0, 84); style = RErr, [String "filename"; String "iface"], []; blocking = false; - deprecated_by = Some "add_drive"; config_only = true; + deprecated_by = Replaced_by "add_drive"; config_only = true; shortdesc = "add a drive read-only specifying the QEMU block emulation to use"; longdesc = "\ This is the same as C<guestfs_add_drive_ro> but it allows you @@ -88,7 +88,7 @@ to specify the QEMU interface emulation to use at run time." }; { defaults with name = "lstatlist"; added = (1, 0, 77); style = RStructList ("statbufs", "stat"), [Pathname "path"; FilenameList "names"], []; - deprecated_by = Some "lstatnslist"; + deprecated_by = Replaced_by "lstatnslist"; shortdesc = "lstat on multiple files"; longdesc = "\ This call allows you to perform the C<guestfs_lstat> operation @@ -108,7 +108,7 @@ for getting extended attributes." }; { defaults with name = "stat"; added = (1, 9, 2); style = RStruct ("statbuf", "stat"), [Pathname "path"], []; - deprecated_by = Some "statns"; + deprecated_by = Replaced_by "statns"; tests = [ InitISOFS, Always, TestResult ( [["stat"; "/empty"]], "ret->size == 0"), [] @@ -122,7 +122,7 @@ This is the same as the L<stat(2)> system call." }; { defaults with name = "lstat"; added = (1, 9, 2); style = RStruct ("statbuf", "stat"), [Pathname "path"], []; - deprecated_by = Some "lstatns"; + deprecated_by = Replaced_by "lstatns"; tests = [ InitISOFS, Always, TestResult ( [["lstat"; "/empty"]], "ret->size == 0"), [] @@ -145,7 +145,7 @@ let daemon_functions = [ style = RErr, [Device "device"; Int "cyls"; Int "heads"; Int "sectors"; StringList "lines"], []; - deprecated_by = Some "part_add"; + deprecated_by = Replaced_by "part_add"; shortdesc = "create partitions on a block device"; longdesc = "\ This is a direct interface to the L<sfdisk(8)> program for creating @@ -174,7 +174,7 @@ C<guestfs_part_init>" }; { defaults with name = "blockdev_setbsz"; added = (1, 9, 3); style = RErr, [Device "device"; Int "blocksize"], []; - deprecated_by = Some "mkfs"; + deprecated_by = Replaced_by "mkfs"; shortdesc = "set blocksize of block device"; longdesc = "\ This call does nothing and has never done anything @@ -186,7 +186,7 @@ C<blocksize> option of C<guestfs_mkfs>." }; { defaults with name = "tgz_in"; added = (1, 0, 3); style = RErr, [FileIn "tarball"; Pathname "directory"], []; - deprecated_by = Some "tar_in"; + deprecated_by = Replaced_by "tar_in"; cancellable = true; tests = [ InitScratchFS, Always, TestResultString ( @@ -202,7 +202,7 @@ I<gzip compressed> tar file) into F<directory>." }; { defaults with name = "tgz_out"; added = (1, 0, 3); style = RErr, [Pathname "directory"; FileOut "tarball"], []; - deprecated_by = Some "tar_out"; + deprecated_by = Replaced_by "tar_out"; cancellable = true; shortdesc = "pack directory into compressed tarball"; longdesc = "\ @@ -212,7 +212,7 @@ it to local file C<tarball>." }; { defaults with name = "set_e2label"; added = (1, 0, 15); style = RErr, [Device "device"; String "label"], []; - deprecated_by = Some "set_label"; + deprecated_by = Replaced_by "set_label"; tests = [ InitBasicFS, Always, TestResultString ( [["set_e2label"; "/dev/sda1"; "testlabel"]; @@ -230,7 +230,7 @@ to return the existing label on a filesystem." }; { defaults with name = "get_e2label"; added = (1, 0, 15); style = RString "label", [Device "device"], []; - deprecated_by = Some "vfs_label"; + deprecated_by = Replaced_by "vfs_label"; shortdesc = "get the ext2/3/4 filesystem label"; longdesc = "\ This returns the ext2/3/4 filesystem label of the filesystem on @@ -239,7 +239,7 @@ C<device>." }; { defaults with name = "set_e2uuid"; added = (1, 0, 15); style = RErr, [Device "device"; String "uuid"], []; - deprecated_by = Some "set_uuid"; + deprecated_by = Replaced_by "set_uuid"; tests = [ InitBasicFS, Always, TestResultString ( [["set_e2uuid"; "/dev/sda1"; stable_uuid]; @@ -267,7 +267,7 @@ of a filesystem." }; { defaults with name = "get_e2uuid"; added = (1, 0, 15); style = RString "uuid", [Device "device"], []; - deprecated_by = Some "vfs_uuid"; + deprecated_by = Replaced_by "vfs_uuid"; tests = [ (* We can't predict what UUID will be, so just check the command run; regression test for RHBZ#597112. *) @@ -285,7 +285,7 @@ C<device>." }; style = RErr, [Device "device"; Int "partnum"; Int "cyls"; Int "heads"; Int "sectors"; String "line"], []; - deprecated_by = Some "part_add"; + deprecated_by = Replaced_by "part_add"; shortdesc = "modify a single partition on a block device"; longdesc = "\ This runs L<sfdisk(8)> option to modify just the single @@ -299,7 +299,7 @@ See also: C<guestfs_part_add>" }; { defaults with name = "sfdisk_l"; added = (1, 0, 26); style = RString "partitions", [Device "device"], []; - deprecated_by = Some "part_list"; + deprecated_by = Replaced_by "part_list"; shortdesc = "display the partition table"; longdesc = "\ This displays the partition table on C<device>, in the @@ -311,7 +311,7 @@ See also: C<guestfs_part_list>" }; { defaults with name = "e2fsck_f"; added = (1, 0, 29); style = RErr, [Device "device"], []; - deprecated_by = Some "e2fsck"; + deprecated_by = Replaced_by "e2fsck"; shortdesc = "check an ext2/ext3 filesystem"; longdesc = "\ This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3 @@ -321,7 +321,7 @@ even if the filesystem appears to be clean (I<-f>)." }; { defaults with name = "mkswap_L"; added = (1, 0, 55); style = RErr, [String "label"; Device "device"], []; - deprecated_by = Some "mkswap"; + deprecated_by = Replaced_by "mkswap"; tests = [ InitEmpty, Always, TestRun ( [["part_disk"; "/dev/sda"; "mbr"]; @@ -338,7 +338,7 @@ a limitation of the kernel or swap tools." }; { defaults with name = "mkswap_U"; added = (1, 0, 55); style = RErr, [String "uuid"; Device "device"], []; - deprecated_by = Some "mkswap"; + deprecated_by = Replaced_by "mkswap"; optional = Some "linuxfsuuid"; tests = [ InitEmpty, Always, TestRun ( @@ -352,7 +352,7 @@ Create a swap partition on C<device> with UUID C<uuid>." }; { defaults with name = "sfdiskM"; added = (1, 0, 55); style = RErr, [Device "device"; StringList "lines"], []; - deprecated_by = Some "part_add"; + deprecated_by = Replaced_by "part_add"; shortdesc = "create partitions on a block device"; longdesc = "\ This is a simplified interface to the C<guestfs_sfdisk> @@ -367,7 +367,7 @@ and C<guestfs_part_disk>" }; { defaults with name = "zfile"; added = (1, 0, 59); style = RString "description", [String "meth"; Pathname "path"], []; - deprecated_by = Some "file"; + deprecated_by = Replaced_by "file"; shortdesc = "determine file type inside a compressed file"; longdesc = "\ This command runs F<file> after first decompressing C<path> @@ -382,7 +382,7 @@ process compressed files." }; name = "egrep"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["egrep"; "abc"; "/test-grep.txt"]], @@ -397,7 +397,7 @@ matching lines." }; name = "fgrep"; added = (1, 0, 66); style = RStringList "lines", [String "pattern"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["fgrep"; "abc"; "/test-grep.txt"]], @@ -412,7 +412,7 @@ matching lines." }; name = "grepi"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["grepi"; "abc"; "/test-grep.txt"]], @@ -427,7 +427,7 @@ matching lines." }; name = "egrepi"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["egrepi"; "abc"; "/test-grep.txt"]], @@ -442,7 +442,7 @@ matching lines." }; name = "fgrepi"; added = (1, 0, 66); style = RStringList "lines", [String "pattern"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["fgrepi"; "abc"; "/test-grep.txt"]], @@ -457,7 +457,7 @@ matching lines." }; name = "zgrep"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zgrep"; "abc"; "/test-grep.txt.gz"]], @@ -472,7 +472,7 @@ matching lines." }; name = "zegrep"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zegrep"; "abc"; "/test-grep.txt.gz"]], @@ -487,7 +487,7 @@ matching lines." }; name = "zfgrep"; added = (1, 0, 66); style = RStringList "lines", [String "pattern"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zfgrep"; "abc"; "/test-grep.txt.gz"]], @@ -503,7 +503,7 @@ matching lines." }; style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zgrepi"; "abc"; "/test-grep.txt.gz"]], @@ -518,7 +518,7 @@ matching lines." }; name = "zegrepi"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zegrepi"; "abc"; "/test-grep.txt.gz"]], @@ -533,7 +533,7 @@ matching lines." }; name = "zfgrepi"; added = (1, 0, 66); style = RStringList "lines", [String "pattern"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zfgrepi"; "abc"; "/test-grep.txt.gz"]], @@ -547,7 +547,7 @@ matching lines." }; { defaults with name = "fallocate"; added = (1, 0, 66); style = RErr, [Pathname "path"; Int "len"], []; - deprecated_by = Some "fallocate64"; + deprecated_by = Replaced_by "fallocate64"; tests = [ InitScratchFS, Always, TestResult ( [["fallocate"; "/fallocate"; "1000000"]; @@ -567,7 +567,7 @@ attaches it as a device." }; name = "setcon"; added = (1, 0, 67); style = RErr, [String "context"], []; optional = Some "selinux"; - deprecated_by = Some "selinux_relabel"; + deprecated_by = Replaced_by "selinux_relabel"; shortdesc = "set SELinux security context"; longdesc = "\ This sets the SELinux security context of the daemon @@ -579,7 +579,7 @@ See the documentation about SELINUX in L<guestfs(3)>." }; name = "getcon"; added = (1, 0, 67); style = RString "context", [], []; optional = Some "selinux"; - deprecated_by = Some "selinux_relabel"; + deprecated_by = Replaced_by "selinux_relabel"; shortdesc = "get SELinux security context"; longdesc = "\ This gets the SELinux security context of the daemon. @@ -590,7 +590,7 @@ and C<guestfs_setcon>" }; { defaults with name = "mkfs_b"; added = (1, 0, 68); style = RErr, [String "fstype"; Int "blocksize"; Device "device"], []; - deprecated_by = Some "mkfs"; + deprecated_by = Replaced_by "mkfs"; tests = [ InitEmpty, Always, TestResultString ( [["part_disk"; "/dev/sda"; "mbr"]; @@ -627,7 +627,7 @@ the requested cluster size." }; { defaults with name = "mke2journal"; added = (1, 0, 68); style = RErr, [Int "blocksize"; Device "device"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; tests = [ InitEmpty, Always, TestResultString ( [["part_init"; "/dev/sda"; "mbr"]; @@ -649,7 +649,7 @@ to the command: { defaults with name = "mke2journal_L"; added = (1, 0, 68); style = RErr, [Int "blocksize"; String "label"; Device "device"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; tests = [ InitEmpty, Always, TestResultString ( [["part_init"; "/dev/sda"; "mbr"]; @@ -668,7 +668,7 @@ This creates an ext2 external journal on C<device> with label C<label>." }; { defaults with name = "mke2journal_U"; added = (1, 0, 68); style = RErr, [Int "blocksize"; String "uuid"; Device "device"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; optional = Some "linuxfsuuid"; tests = [ InitEmpty, Always, TestResultString ( @@ -688,7 +688,7 @@ This creates an ext2 external journal on C<device> with UUID C<uuid>." }; { defaults with name = "mke2fs_J"; added = (1, 0, 68); style = RErr, [String "fstype"; Int "blocksize"; Device "device"; Device "journal"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; shortdesc = "make ext2/3/4 filesystem with external journal"; longdesc = "\ This creates an ext2/3/4 filesystem on C<device> with @@ -702,7 +702,7 @@ See also C<guestfs_mke2journal>." }; { defaults with name = "mke2fs_JL"; added = (1, 0, 68); style = RErr, [String "fstype"; Int "blocksize"; Device "device"; String "label"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; shortdesc = "make ext2/3/4 filesystem with external journal"; longdesc = "\ This creates an ext2/3/4 filesystem on C<device> with @@ -713,7 +713,7 @@ See also C<guestfs_mke2journal_L>." }; { defaults with name = "mke2fs_JU"; added = (1, 0, 68); style = RErr, [String "fstype"; Int "blocksize"; Device "device"; String "uuid"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; optional = Some "linuxfsuuid"; shortdesc = "make ext2/3/4 filesystem with external journal"; longdesc = "\ @@ -725,7 +725,7 @@ See also C<guestfs_mke2journal_U>." }; { defaults with name = "dd"; added = (1, 0, 80); style = RErr, [Dev_or_Path "src"; Dev_or_Path "dest"], []; - deprecated_by = Some "copy_device_to_device"; + deprecated_by = Replaced_by "copy_device_to_device"; tests = [ InitScratchFS, Always, TestResult ( [["mkdir"; "/dd"]; @@ -749,7 +749,7 @@ This command cannot do partial copies { defaults with name = "txz_in"; added = (1, 3, 2); style = RErr, [FileIn "tarball"; Pathname "directory"], []; - deprecated_by = Some "tar_in"; + deprecated_by = Replaced_by "tar_in"; optional = Some "xz"; cancellable = true; tests = [ InitScratchFS, Always, TestResultString ( @@ -765,7 +765,7 @@ I<xz compressed> tar file) into F<directory>." }; { defaults with name = "txz_out"; added = (1, 3, 2); style = RErr, [Pathname "directory"; FileOut "tarball"], []; - deprecated_by = Some "tar_out"; + deprecated_by = Replaced_by "tar_out"; optional = Some "xz"; cancellable = true; shortdesc = "pack directory into compressed tarball"; longdesc = "\ @@ -775,7 +775,7 @@ it to local file C<tarball> (as an xz compressed tar archive)." }; { defaults with name = "llz"; added = (1, 17, 6); style = RString "listing", [Pathname "directory"], []; - deprecated_by = Some "lgetxattrs"; + deprecated_by = Replaced_by "lgetxattrs"; shortdesc = "list the files in a directory (long format with SELinux contexts)"; longdesc = "\ List the files in F<directory> in the format of 'ls -laZ'. @@ -786,7 +786,7 @@ is I<not> intended that you try to parse the output string." }; { defaults with name = "write_file"; added = (0, 0, 8); style = RErr, [Pathname "path"; String "content"; Int "size"], []; - protocol_limit_warning = true; deprecated_by = Some "write"; + protocol_limit_warning = true; deprecated_by = Replaced_by "write"; (* Regression test for RHBZ#597135. *) tests = [ InitScratchFS, Always, TestLastFail @@ -808,7 +808,7 @@ characters does I<not> work, even if the length is specified." }; { defaults with name = "copy_size"; added = (1, 0, 87); style = RErr, [Dev_or_Path "src"; Dev_or_Path "dest"; Int64 "size"], []; - progress = true; deprecated_by = Some "copy_device_to_device"; + progress = true; deprecated_by = Replaced_by "copy_device_to_device"; tests = [ InitScratchFS, Always, TestResult ( [["mkdir"; "/copy_size"]; @@ -828,7 +828,7 @@ is not large enough." }; { defaults with name = "ntfsresize_size"; added = (1, 3, 14); style = RErr, [Device "device"; Int64 "size"], []; - optional = Some "ntfsprogs"; deprecated_by = Some "ntfsresize"; + optional = Some "ntfsprogs"; deprecated_by = Replaced_by "ntfsresize"; shortdesc = "resize an NTFS filesystem (with size)"; longdesc = "\ This command is the same as C<guestfs_ntfsresize> except that it diff --git a/generator/actions_inspection_deprecated.ml b/generator/actions_inspection_deprecated.ml index 04fb143..5ca062c 100644 --- a/generator/actions_inspection_deprecated.ml +++ b/generator/actions_inspection_deprecated.ml @@ -26,7 +26,7 @@ let non_daemon_functions = [ { defaults with name = "inspect_list_applications"; added = (1, 7, 8); style = RStructList ("applications", "application"), [Mountable "root"], []; - deprecated_by = Some "inspect_list_applications2"; + deprecated_by = Replaced_by "inspect_list_applications2"; shortdesc = "get list of applications installed in the operating system"; longdesc = "\ Return the list of applications installed in the operating system. diff --git a/generator/actions_properties_deprecated.ml b/generator/actions_properties_deprecated.ml index 3fe8fef..def17b9 100644 --- a/generator/actions_properties_deprecated.ml +++ b/generator/actions_properties_deprecated.ml @@ -30,7 +30,7 @@ let non_daemon_functions = [ style = RErr, [OptString "hv"], []; fish_alias = ["qemu"]; config_only = true; blocking = false; - deprecated_by = Some "set_hv"; + deprecated_by = Replaced_by "set_hv"; shortdesc = "set the hypervisor binary (usually qemu)"; longdesc = "\ Set the hypervisor binary (usually qemu) that we will use. @@ -55,7 +55,7 @@ the qemu binary at the same time as the handle is created." }; name = "get_qemu"; added = (1, 0, 6); style = RConstString "hv", [], []; blocking = false; - deprecated_by = Some "get_hv"; + deprecated_by = Replaced_by "get_hv"; tests = [ InitNone, Always, TestRun ( [["get_qemu"]]), [] @@ -72,7 +72,7 @@ return the default qemu binary name." }; style = RErr, [Bool "selinux"], []; fish_alias = ["selinux"]; config_only = true; blocking = false; - deprecated_by = Some "selinux_relabel"; + deprecated_by = Replaced_by "selinux_relabel"; shortdesc = "set SELinux enabled or disabled at appliance boot"; longdesc = "\ This sets the selinux flag that is passed to the appliance @@ -88,7 +88,7 @@ see L<guestfs(3)>." }; name = "get_selinux"; added = (1, 0, 67); style = RBool "selinux", [], []; blocking = false; - deprecated_by = Some "selinux_relabel"; + deprecated_by = Replaced_by "selinux_relabel"; shortdesc = "get SELinux enabled flag"; longdesc = "\ This returns the current setting of the selinux flag which @@ -102,7 +102,7 @@ see L<guestfs(3)>." }; style = RErr, [String "backend"], []; fish_alias = ["attach-method"]; config_only = true; blocking = false; - deprecated_by = Some "set_backend"; + deprecated_by = Replaced_by "set_backend"; shortdesc = "set the backend"; longdesc = "\ Set the method that libguestfs uses to connect to the backend @@ -114,7 +114,7 @@ See L<guestfs(3)/BACKEND>." }; name = "get_attach_method"; added = (1, 9, 8); style = RString "backend", [], []; blocking = false; - deprecated_by = Some "get_backend"; + deprecated_by = Replaced_by "get_backend"; tests = [ InitNone, Always, TestRun ( [["get_attach_method"]]), [] diff --git a/generator/c.ml b/generator/c.ml index 1cb0880..606c898 100644 --- a/generator/c.ml +++ b/generator/c.ml @@ -445,11 +445,14 @@ extern \"C\" { #endif /* Define GUESTFS_WARN_DEPRECATED=1 to warn about deprecated API functions. */ -#define GUESTFS_DEPRECATED_BY(s) +#define GUESTFS_DEPRECATED_NO_REPLACEMENT +#define GUESTFS_DEPRECATED_REPLACED_BY(s) #if GUESTFS_WARN_DEPRECATED # if defined(__GNUC__) && GUESTFS_GCC_VERSION >= 40500 /* gcc >= 4.5 */ -# undef GUESTFS_DEPRECATED_BY -# define GUESTFS_DEPRECATED_BY(s) __attribute__((__deprecated__(\"change the program to use guestfs_\" s \" instead of this deprecated function\"))) +# undef GUESTFS_DEPRECATED_NO_REPLACEMENT +# undef GUESTFS_DEPRECATED_REPLACED_BY +# define GUESTFS_DEPRECATED_NO_REPLACEMENT __attribute__((__deprecated__)) +# define GUESTFS_DEPRECATED_REPLACED_BY(s) __attribute__((__deprecated__(\"change the program to use guestfs_\" s \" instead of this deprecated function\"))) # endif #endif /* GUESTFS_WARN_DEPRECATED */ @@ -562,17 +565,17 @@ typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque, int proc_nr, in #endif extern GUESTFS_DLL_PUBLIC void guestfs_set_log_message_callback (guestfs_h *g, guestfs_log_message_cb cb, void *opaque) - GUESTFS_DEPRECATED_BY(\"set_event_callback\"); + GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\"); extern GUESTFS_DLL_PUBLIC void guestfs_set_subprocess_quit_callback (guestfs_h *g, guestfs_subprocess_quit_cb cb, void *opaque) - GUESTFS_DEPRECATED_BY(\"set_event_callback\"); + GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\"); extern GUESTFS_DLL_PUBLIC void guestfs_set_launch_done_callback (guestfs_h *g, guestfs_launch_done_cb cb, void *opaque) - GUESTFS_DEPRECATED_BY(\"set_event_callback\"); + GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\"); #define GUESTFS_HAVE_SET_CLOSE_CALLBACK 1 extern GUESTFS_DLL_PUBLIC void guestfs_set_close_callback (guestfs_h *g, guestfs_close_cb cb, void *opaque) - GUESTFS_DEPRECATED_BY(\"set_event_callback\"); + GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\"); #define GUESTFS_HAVE_SET_PROGRESS_CALLBACK 1 extern GUESTFS_DLL_PUBLIC void guestfs_set_progress_callback (guestfs_h *g, guestfs_progress_cb cb, void *opaque) - GUESTFS_DEPRECATED_BY(\"set_event_callback\"); + GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\"); /* Private data area. */ #define GUESTFS_HAVE_SET_PRIVATE 1 @@ -662,8 +665,12 @@ extern GUESTFS_DLL_PUBLIC void *guestfs_next_private (guestfs_h *g, const char * generate_prototype ~single_line:true ~semicolon:false ~dll_public:true ~handle:"g" ~prefix:"guestfs_" shortname style; (match deprecated_by with - | Some fn -> pr "\n GUESTFS_DEPRECATED_BY (%S);\n" fn - | None -> pr ";\n" + | Not_deprecated -> + pr ";\n" + | Replaced_by fn -> + pr "\n GUESTFS_DEPRECATED_REPLACED_BY (%S);\n" fn + | Deprecated_no_replacement -> + pr "\n GUESTFS_DEPRECATED_NO_REPLACEMENT;\n" ); if optargs <> [] then ( diff --git a/generator/checks.ml b/generator/checks.ml index 63536e5..788a116 100644 --- a/generator/checks.ml +++ b/generator/checks.ml @@ -184,7 +184,7 @@ let () = failwithf "%s: guestfish alias %s should not contain '_'" name n ) f.fish_alias; (match f.deprecated_by with - | Some n -> + | Replaced_by n -> (* 'n' must be a cross-ref to the name of another action. *) if not (List.exists ( function @@ -192,7 +192,7 @@ let () = | _ -> false ) actions) then failwithf "%s: deprecated_by flag must be cross-reference to another action" name - | None -> () + | Not_deprecated | Deprecated_no_replacement -> () ); (match f.optional with | Some n -> diff --git a/generator/docstrings.ml b/generator/docstrings.ml index acfdb53..2ce595d 100644 --- a/generator/docstrings.ml +++ b/generator/docstrings.ml @@ -39,8 +39,9 @@ of somewhere between 2MB and 4MB. See L<guestfs(3)/PROTOCOL LIMITS>." let deprecation_notice ?(prefix = "") ?(replace_underscores = false) = function - | { deprecated_by = None } -> None - | { deprecated_by = Some alt } -> + | { deprecated_by = Not_deprecated } -> None + + | { deprecated_by = Replaced_by alt } -> let alt = if replace_underscores then String.replace_char alt '_' '-' else alt in let txt = @@ -52,6 +53,15 @@ fact that they are deprecated indicates that there are problems with correct use of these functions." prefix alt in Some txt + | { deprecated_by = Deprecated_no_replacement } -> + Some "I<This function is deprecated.> +There is no replacement. Consult the API documentation in +L<guestfs(3)> for further information. + +Deprecated functions will not be removed from the API, but the +fact that they are deprecated indicates that there are problems +with correct use of these functions." + let version_added = function | { added = (0, 0, release) } -> Some (sprintf "0.%d" release) | { added = ((0|1) as major, minor, release) } -> diff --git a/generator/java.ml b/generator/java.ml index 8f71feb..83f2e65 100644 --- a/generator/java.ml +++ b/generator/java.ml @@ -297,9 +297,11 @@ public class GuestFS { | Some version -> pr " * @since %s\n" version ); (match f with - | { deprecated_by = None } -> () - | { deprecated_by = Some alt } -> + | { deprecated_by = Not_deprecated } -> () + | { deprecated_by = Replaced_by alt } -> pr " * @deprecated In new code, use {@link #%s} instead\n" alt + | { deprecated_by = Deprecated_no_replacement } -> + pr " * @deprecated\n" ); pr " * @throws LibGuestFSException If there is a libguestfs error.\n"; pr " */\n"; @@ -307,8 +309,9 @@ public class GuestFS { pr " "; let deprecated = match f with - | { deprecated_by = None } -> false - | { deprecated_by = Some _ } -> true in + | { deprecated_by = Not_deprecated } -> false + | { deprecated_by = Replaced_by _ | Deprecated_no_replacement } -> + true in generate_java_prototype ~public:true ~semicolon:false ~deprecated f.name f.style; pr "\n"; pr " {\n"; diff --git a/generator/ruby.ml b/generator/ruby.ml index c938bc9..594036d 100644 --- a/generator/ruby.ml +++ b/generator/ruby.ml @@ -146,9 +146,12 @@ and generate_ruby_c actions () = | Some version -> doc ^ (sprintf "\n *\n * [Since] Added in version %s." version) in let doc = match f with - | { deprecated_by = None } -> doc - | { deprecated_by = Some alt } -> - doc ^ (sprintf "\n *\n * [Deprecated] In new code, use rdoc-ref:%s instead." alt) in + | { deprecated_by = Not_deprecated } -> doc + | { deprecated_by = Replaced_by alt } -> + doc ^ + sprintf "\n *\n * [Deprecated] In new code, use rdoc-ref:%s instead." alt + | { deprecated_by = Deprecated_no_replacement } -> + doc ^ "\n *\n * [Deprecated]" in let doc = match f.optional with | None -> doc diff --git a/generator/types.ml b/generator/types.ml index fd9f215..3fa96fd 100644 --- a/generator/types.ml +++ b/generator/types.ml @@ -342,6 +342,11 @@ type visibility = type version = int * int * int +type deprecated_by = + | Not_deprecated (* function not deprecated *) + | Replaced_by of string (* replaced by another function *) + | Deprecated_no_replacement (* deprecated with no replacement *) + (* Type of an action as declared in Actions module. *) type action = { name : string; (* name, not including "guestfs_" *) @@ -358,7 +363,7 @@ type action = { fish_alias : string list; (* alias(es) for this cmd in guestfish *) fish_output : fish_output_t option; (* how to display output in guestfish *) visibility: visibility; (* The visbility of function *) - deprecated_by : string option; (* function is deprecated, use .. instead *) + deprecated_by : deprecated_by; (* function is deprecated *) optional : string option; (* function is part of an optional group *) progress : bool; (* function can generate progress messages *) camel_name : string; (* Pretty camel case name of @@ -407,7 +412,7 @@ let defaults = { name = ""; shortdesc = ""; longdesc = ""; protocol_limit_warning = false; fish_alias = []; fish_output = None; visibility = VPublic; - deprecated_by = None; optional = None; + deprecated_by = Not_deprecated; optional = None; progress = false; camel_name = ""; cancellable = false; config_only = false; once_had_no_optargs = false; blocking = true; wrapper = true; -- 2.9.3