Richard W.M. Jones
2017-Mar-03 10:18 UTC
[Libguestfs] [PATCH] generator: Allow actions to be deprecated with no replacement.
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
Pino Toscano
2017-Mar-03 15:31 UTC
Re: [Libguestfs] [PATCH] generator: Allow actions to be deprecated with no replacement.
On Friday, 3 March 2017 11:18:26 CET Richard W.M. Jones wrote:> There is precisely one such function at the moment > (guestfs_wait_ready). > ---Mostly LGTM, few notes below.> 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"The "Deprecated" tag needs a text, so I'd just note to not use it anymore.> ); > (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"Ditto.> 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" > );Ditto.> 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 docDitto.> 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 > @@ -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 anythingThis maybe could just become Deprecated_no_replacement, since it never did anything anyway. Thanks, -- Pino Toscano
Richard W.M. Jones
2017-Mar-03 16:40 UTC
Re: [Libguestfs] [PATCH] generator: Allow actions to be deprecated with no replacement.
On Fri, Mar 03, 2017 at 04:31:45PM +0100, Pino Toscano wrote:> On Friday, 3 March 2017 11:18:26 CET Richard W.M. Jones wrote: > > There is precisely one such function at the moment > > (guestfs_wait_ready). > > --- > > Mostly LGTM, few notes below.Thanks - I will push it with the changes you have noted below. Rich.> > 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" > > The "Deprecated" tag needs a text, so I'd just note to not use it anymore. > > > ); > > (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" > > Ditto. > > > 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" > > ); > > Ditto. > > > 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 > > Ditto. > > > 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 > > @@ -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 > > This maybe could just become Deprecated_no_replacement, since it never > did anything anyway. > > Thanks, > -- > Pino Toscano> _______________________________________________ > Libguestfs mailing list > Libguestfs@redhat.com > https://www.redhat.com/mailman/listinfo/libguestfs-- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com virt-df lists disk usage of guests without needing to install any software inside the virtual machine. Supports Linux and Windows. http://people.redhat.com/~rjones/virt-df/
Apparently Analagous Threads
- Re: [PATCH] generator: Allow actions to be deprecated with no replacement.
- [PATCH 1/2] generator: Simplify the handling of string parameters.
- [PATCH] generator: java: Don't link to undocumented methods.
- [PATCH] generator: Move some deprecated functions to actions_core_deprecated.ml.
- [PATCH 7/7] perl: show warnings for deprecated functions