Merge pull request ocaml#316 from alainfrisch/deprecated_unit

Allowing to mark compilation units and sub-modules as deprecated

Author: alainfrisch

Changes

@@ -98,6 +98,8 @@ Compilers:
   (Pierre Chambart, Xavier Leroy)
 - PR#7022, GPR#259: unbox float and boxed ints earlier, avoid second pass
   (Alain Frisch)
+- PR#7064, GPR#316: allowing to mark compilation units and sub-modules as
+  deprecated (Alain Frisch)
 - GPR#263: improve code generation for if-equivalents of (&&) and (||)
   (Pierre Chambart)
 - GPR#271: Fix incorrect mutability flag when records are built using "with"

driver/compile.ml

@@ -42,7 +42,8 @@ let interface ppf sourcefile outputprefix =
   Typecore.force_delayed_checks ();
   Warnings.check_fatal ();
   if not !Clflags.print_types then begin
-    let sg = Env.save_signature sg modulename (outputprefix ^ ".cmi") in
+    let deprecated = Typetexp.deprecated_of_sig ast in
+    let sg = Env.save_signature ~deprecated sg modulename (outputprefix ^ ".cmi") in
     Typemod.save_signature modulename tsg outputprefix sourcefile
       initial_env sg ;
   end

driver/optcompile.ml

@@ -43,7 +43,8 @@ let interface ppf sourcefile outputprefix =
   Typecore.force_delayed_checks ();
   Warnings.check_fatal ();
   if not !Clflags.print_types then begin
-    let sg = Env.save_signature sg modulename (outputprefix ^ ".cmi") in
+    let deprecated = Typetexp.deprecated_of_sig ast in
+    let sg = Env.save_signature ~deprecated sg modulename (outputprefix ^ ".cmi") in
     Typemod.save_signature modulename tsg outputprefix sourcefile
       initial_env sg ;
   end

manual/manual/refman/exten.etex

@@ -1463,7 +1463,11 @@ Some attributes are understood by the type-checker:
   Can be applied to most kind of items in signatures or
   structures.  When the element is later referenced, a warning (3) is
   triggered.  If the payload of the attribute is a string literal,
-  the warning message includes this text.
+  the warning message includes this text.  It is also possible
+  to use this ``ocaml.deprecated'' as a floating attribute
+  on top of an ``.mli'' file (i.e. before any other non-attribute
+  item) or on top of an ``.ml'' file without a corresponding
+  interface; this marks the unit itself as being deprecated.
 \item
   ``ocaml.ppwarning'' or ``ppwarning'', in any context, with
   a string literal payload.  The text is reported as warning (22)
@@ -1478,6 +1482,7 @@ module X = struct
   [@@@warning "+9"]  (* locally enable warning 9 in this structure *)
   ...
 end
+  [@@deprecated "Please is module 'Y' instead."]
 
 let x = begin[@warning "+9] ... end in ....
 

testsuite/tests/warnings/Makefile

@@ -12,27 +12,27 @@
 
 BASEDIR=../..
 FLAGS=-w A
-EXECNAME=./program
 
 run-all:
+	@$(OCAMLC) $(FLAGS) -c deprecated_module.mli
 	@for file in *.ml; do \
 	  printf " ... testing '$$file':"; \
 	  F="`basename $$file .ml`"; \
-	  $(OCAMLC) $(FLAGS) -o $(EXECNAME) $$file 2>$$F.result; \
+	  $(OCAMLC) $(FLAGS) -c $$file 2>$$F.result; \
 	  $(DIFF) $$F.reference $$F.result >/dev/null \
 	  && echo " => passed" || echo " => failed"; \
 	done;
 	@for file in *.opt.ml; do \
-	  printf " ... testing '$$file':"; \
+	  printf " ... testing '$$file' with ocamlopt:"; \
 	  F="`basename $$file .ml`"; \
-	  $(OCAMLOPT) $(FLAGS) -o $(EXECNAME) $$file 2>$$F.opt_result; \
+	  $(OCAMLOPT) $(FLAGS) -c $$file 2>$$F.opt_result; \
 	  $(DIFF) $$F.opt_reference $$F.opt_result >/dev/null \
 	  && echo " => passed" || echo " => failed"; \
 	done;
 
 promote: defaultpromote
 
 clean: defaultclean
-	@rm -f *.result $(EXECNAME)
+	@rm -f *.result
 
 include $(BASEDIR)/makefiles/Makefile.common

testsuite/tests/warnings/deprecated_module.ml

@@ -0,0 +1,9 @@
+module M = struct
+  type t = int
+
+  let x = 10
+end
+[@@ocaml.deprecated]
+
+let _ = M.x
+include M

testsuite/tests/warnings/deprecated_module.mli

@@ -0,0 +1,13 @@
+[@@@ocaml.deprecated {|
+  As you could guess, Deprecated_module is deprecated.
+  Please use something else!
+|} ]
+
+module M: sig
+  val x: int
+    [@@ocaml.deprecated]
+
+  type t
+    [@@ocaml.deprecated]
+end
+[@@ocaml.deprecated]

testsuite/tests/warnings/deprecated_module.reference

@@ -0,0 +1,4 @@
+File "deprecated_module.ml", line 8, characters 8-11:
+Warning 3: deprecated: module M
+File "deprecated_module.ml", line 9, characters 8-9:
+Warning 3: deprecated: module M

testsuite/tests/warnings/deprecated_module_use.ml

@@ -0,0 +1,6 @@
+open Deprecated_module
+
+type s = M.t
+
+open M
+let _ = x

testsuite/tests/warnings/deprecated_module_use.reference

@@ -0,0 +1,14 @@
+File "deprecated_module_use.ml", line 1, characters 5-22:
+Warning 3: deprecated: module Deprecated_module
+
+  As you could guess, Deprecated_module is deprecated.
+  Please use something else!
+
+File "deprecated_module_use.ml", line 3, characters 9-12:
+Warning 3: deprecated: module Deprecated_module.M
+File "deprecated_module_use.ml", line 3, characters 9-12:
+Warning 3: deprecated: Deprecated_module.M.t
+File "deprecated_module_use.ml", line 5, characters 5-6:
+Warning 3: deprecated: module Deprecated_module.M
+File "deprecated_module_use.ml", line 6, characters 8-9:
+Warning 3: deprecated: Deprecated_module.M.x

typing/cmi_format.ml

@@ -10,7 +10,9 @@
 (*                                                                     *)
 (***********************************************************************)
 
-type pers_flags = Rectypes
+type pers_flags =
+  | Rectypes
+  | Deprecated of string
 
 type error =
     Not_an_interface of string

typing/cmi_format.mli

@@ -10,7 +10,9 @@
 (*                                                                     *)
 (***********************************************************************)
 
-type pers_flags = Rectypes
+type pers_flags =
+  | Rectypes
+  | Deprecated of string
 
 type cmi_infos = {
     cmi_name : string;