From 6b3ccfcc161800c5a730cdac819ce5f816a2fd3d Mon Sep 17 00:00:00 2001 From: Marius Vollmer Date: Wed, 2 May 2001 00:53:07 +0000 Subject: Added section about the handling of deprecated features. --- README | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) (limited to 'README') diff --git a/README b/README index 0598f6ef3..57cc6c7c3 100644 --- a/README +++ b/README @@ -86,6 +86,56 @@ license statement as found in any individual file that it applies to: whether to permit this exception to apply to your modifications. If you do not wish that, delete this exception notice. +Handling of Deprecated Features ====================================== + +Guile may contain features that are `deprecated'. When a feature is +deprecated, it means that it is still there and fully functional, but +that there is a better way of achieving the same thing, and we'd +rather have you use this better way. This allows us to eventually +remove the old implementation and helps to keep Guile reasonably clean +of historic baggage. + +See the file NEWS for a list of features that are currently +deprecated. Each entry will also tell you what you should replace +your code with. + +To give you some help with this process, and to encourage (OK, nudge) +people to switch to the newer methods, Guile can emit warnings or +errors when you use a deprecated feature. There is quite a range of +possibilities, from being completely silent to giving errors at link +time. What exactly happens is determined both by the value of the +`--enable-deprecated' configuration option when Guile was built, and +by the GUILE_WARN_DEPRECATED environment variable. + +It works like this: + + When Guile has been configured with `--enable-deprecated=no' (or, + equivalently, with `--disable-deprecated') then all deprecated + features are omitted from Guile. You will get "undefined + reference", "variable unbound" or similar errors when you try to use + them. + + When `--enable-deprecated=LEVEL' has been specified (for LEVEL not + "no"), LEVEL will be used as the default value of the environment + variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to + "summary", however. + + When GUILE_WARN_DEPRECATION has the value "no", nothing special will + happen when a deprecated feature is used. + + When GUILE_WARN_DEPRECATION has the value "summary", and a deprecated + feature has been used, Guile will print this message at exit: + + Some deprecated features have been used. Set the environment + variable GUILE_WARN_DEPRECATED to "detailed" and rerun the program + to get more information. Set it to "no" to suppress this message. + + When GUILE_WARN_DEPRECATION has the value "detailed", a detailed + warning is emitted immediatly for the first use of a deprecated + feature. + +The default is `--enable-deprecation=yes'. + About This Distribution ============================================== Interesting files include: -- cgit v1.2.3