OPENSTEP Release 4.2 Copyright (C) 1996-1997 by NeXT Software, Inc. All Rights Reserved.
Title: OPENSTEP 4.2 Prerelease 1 Release Notes: Notes to Prior Users of Foundation
Entry Number: xxxx
Last Updated: January 24, 1997
OPENSTEP 4.2 Release Notes:
Notes for Users of Foundation Framework Prior to OPENSTEP 4.0
For general Foundation Framework release notes, see the release note Foundation.rtf.
In the document below, "4.0" and "OPENSTEP 4.0" refer to all products that shipped with the 4.0 Foundation: OPENSTEP 4.0, D'OLE 4.0, and PDO 4.0 for HP-UXTM and SolarisTM.
There were several releases of the Foundation Framework prior to OPENSTEP 4.0. Foundation shipped with:
This document only describes API changes that have been made between those releases and OPENSTEP 4.0. (For changes since OPENSTEP 4.0, see the release note Foundation.rtf.) The semantics of many things have changed, but most not in a way that will affect programs (NEXTSTEP 3.3 Foundation-based programs and EOF 1.1 programs, being older, are more likely to be affected). Unfortunately, there is no single source for information about such changes--refer to the Foundation Framework Reference and specific class specifications for the current behavior. This document does not describe extensions to Foundation provided by various NeXT products (for example, WebObjects or EOF).
Foundation is now packaged as a ProjectBuilder framework, and resides in /NextLibrary/Frameworks/Foundation.framework. The headers can be found in /NextLibrary/Frameworks/Foundation.framework/Headers.
All programs based upon previous version of Foundation should be recompiled (even if no conversion is necessary) to function with this version of Foundation. Compiling against the old static "shlib" (the shared library shipped with NEXTSTEP 3.3, EOF 1.1, and PDO 3.0, and used by WebObjects) is not supported in OPENSTEP 4.0 (without EOF 1.1 installed).
This section is divided into a subsection for each of the previous releases of the Foundation Framework. There are no specific notes for Enterprise Objects Framework 1.0, Portable Distributed Objects 3.0, or WebObjects 1.0 developers; please refer to the section for Enterprise Objects Framework 1.1 developers. The API of the Foundation shipped with Portable Distributed Objects 3.0 and WebObjects 1.0 was identical to that in Enterprise Objects Framework 1.1 (other than extensions made by those products).
Notes Specific to NEXTSTEP 3.3 Developers
Items in the tables below (in the section titled Tables Showing Foundation API Changes) that are marked with "(NS33)" are changes made to Foundation between NEXTSTEP 3.3 and OPENSTEP 4.0. Also see the general comments in the section Notes Specific to Enterprise Objects Framework 1.1 Developers below. NEXTSTEP 3.3 developers should note the following additions to those comments:
* The header NXAutoreleaseConnection.h was not in NEXTSTEP 3.3. Comments referring to this header do not apply to NEXTSTEP 3.3 developers.
* Two additional headers, NSLock.h and NSThread.h, were not in NEXTSTEP 3.3, but are in OPENSTEP 4.0.
Notes Specific to Enterprise Objects Framework 1.1 Developers
Items in the tables below (in the section titled Tables Showing Foundation API Changes) marked with "(EOF11)" are changes made to Foundation between EOF 1.1 and OPENSTEP 4.0.
Some additional changes are not contained in the tables or are of particular note:
* Headers are now imported as <Foundation/...>, rather than <foundation/...>.
* The structure of imports has changed. The Foundation headers import all ANSI C headers they need and some of the Objective-C interfaces, but none of the operating system interfaces. The set of headers imported by each header has also changed in many places. Where a project was getting a header imported "for free" before, it may now need to import additional headers in order to compile.
* The header NXAutoreleaseConnection.h has been removed. Its contents have been moved to NSCompatibility.h.
* A Foundation.h header has been added, which includes the 15 ANSI C headers, and all Foundation headers except NSCompatibility.h and NSDebug.h.
* The top-level NSAutoreleasePool is no longer created for automatically--a program needs to create it itself. See the Foundation Framework Reference and the NSAutoreleasePool class specification for more information on creating autorelease pools.
* NSDictionary no longer constrains keys to be instances of NSString. Any object that meaningfully responds to -hash, -isEqual:, and -copyWithZone: can be an NSDictionary key.
* The name of the exception variable in the NS_HANDLER...NS_ENDHANDLER region has been changed from exception to localException.
* Some methods that are not in OpenStep, and were not guarded with #if !defined(STRICT_OPENSTEP), now are guarded.
* NSObject no longer conforms to the NSCoding protocol. Instead, the classes that can be archived or distributed, and their subclasses, conform to the protocol explicitly.
* NSBundle's and NSNotificationCenter's instance variables are now declared @private.
* The type of the parameter to NSBundle's +bundleForClass: method changed from id to Class.
* The type of the parameter to NSValue's +valueWithPointer: method changed from void * to const void *.
* The typedef NSStringEncoding in NSString.h has changed from a typedef'd enumeration to a typedef'd scalar.
* The value of the enumeration constant NSUnicodeStringEncoding in NSString.h has changed from 0 to 10.
* The location of the resources has changed, and can now be found in the Foundation framework directory. If, in a previous release of the Foundation, your application was poking around in the Foundation resources, you should carefully consider why you were doing so, and stop doing it if possible.
* The declarations of the NSAutoreleasePool debugging methods and aids have moved from NSAutoreleasePool.h to NSDebug.h. Some of the methods are destined for obsolescence, and some new methods have been added.
* The header NSObjCRuntime.h now imports the headers objc/zone.h and stdarg.h.
* Many declarations and definitions were removed from the header NSUtilities.h and moved elsewhere, but all the previous material is still defined by importing NSUtilities.h. The headers to which things were moved are NSEnumerator.h, NSObjCRuntime.h, NSDictionary.h, and NSString.h.
Finally, the Foundation shipped with EOF 1.1 did not contain much of the functionality of the Foundation in OPENSTEP 4.0. These headers, and all the API they declare, were added between EOF 1.1 and OPENSTEP 4.0:
The API added by these headers is not included in the tables below.
Notes Specific to D'OLE 3.5 Developers
Items in the tables below (in the section titled Tables Showing Foundation API Changes) marked with "(40PR1)" are changes made to Foundation between OPENSTEP 4.0 PR1 and OPENSTEP 4.0. This symbol also marks changes that apply to D'OLE 3.5 developers, with the exceptions noted below. See also the general comments in the section Notes Specific to OPENSTEP 4.0 PR1 Developers below.
The following are exceptions to the changes noted between OPENSTEP 4.0 PR1 and OPENSTEP 4.0, for D'OLE 3.5 developers:
* The header NSPPL.h isn't in D'OLE 3.5, but is in OPENSTEP 4.0. API changes referring to this header do not apply to D'OLE 3.5 developers.
* These methods were in D'OLE 3.5, but not in OPENSTEP 4.0 PR1:
Items in the tables below (in the section titled Tables Showing Foundation API Changes) marked with "(40PR1)" are changes made to Foundation between OPENSTEP 4.0 PR1 and OPENSTEP 4.0.
Some additional changes are not contained in the tables or are of particular note:
* All applications, frameworks, libraries, bundles, tools, etc. compiled in PR1 should be recompiled.
* The header file NSAccount.h has been removed from Foundation. This header was NeXT-specific.
* The header file NSByteStore.h has been removed from Foundation (both from OpenStep and from NeXT's implementation).
* The import of the header NSDebug.h has been removed from Foundation.h; however, it still exists. This header contains features intended for debugging, but not for general use.
* Foundation.h now imports the 15 ANSI C headers (assert.h, ctype.h, errno.h, float.h, limits.h, locale.h, math.h, setjmp.h, signal.h, stdarg.h, stddef.h, stdio.h, stdlib.h, string.h, time.h) as a convenience.
* The header file NSObjCRuntime.h imported six obsolete headers (ansi/ansi.h, objc/typedstream.h, objc/objc-class.h, architecture/byte_order.h, objc/hashtable.h, streams/streams.h) in PR1. It no longer does so. This change may mean that some of these headers may need to be explicitly imported for code written on OPENSTEP 4.0 PR1 to recompile.
* A STRICT_OPENSTEP preprocessor guard now surrounds all API in the headers NSDecimal.h and NSDecimalNumber.h.
* The macro FOUNDATION_EXPORT is now always explicitly defined on WindowsTM (that is, it cannot be predefined with the -D compiler option) in NSObjCRuntime.h.
* A new header and related functionality, NSTask.h, was added.
* See also changes noted in the section Notes Specific to OPENSTEP 4.0 PR2 Developers. All changes listed apply to OPENSTEP 4.0 PR1 developers.
Notes Specific to OPENSTEP 4.0 PR2 Developers
Items in the tables below (in the section titled Tables Showing Foundation API Changes) marked with "(40PR2)" are changes made to Foundation between OPENSTEP 4.0 PR2 and OPENSTEP 4.0.
Some additional changes are not contained in the tables or are of particular note. This list of changes applies to both OPENSTEP 4.0 PR1 and PR2 developers:
* The size of NSPort and NSRunLoop instances has changed. The NSPort class has become abstract and no longer has any instance variables. Applications, tools, frameworks, bundles, or libraries with subclasses of these two classes must be recompiled.
* The header file NSPosixFileDescriptor.h has been removed from Foundation. This header was NeXT-specific. The header NSFileHandle.h provides portable replacement functionality.
* A few new headers have been added. The API in these headers is not included in the tables below:
* Many declarations and definitions were removed from the header NSUtilities.h and moved elsewhere, but all the previous material is still defined by importing NSUtilities.h. The headers to which things were moved are NSEnumerator.h, NSObjCRuntime.h, NSDictionary.h, and NSString.h.
* The header NSObjCRuntime.h now imports the headers objc/zone.h and stdarg.h.
* The type of the parameter to NSTask's -setStandardInput:, -setStandardOutput:, and -setStandardError: methods has changed from NSPosixFileDescriptor * to id.
* The declarations of the NSAutoreleasePool debugging methods and aids have moved from NSAutoreleasePool.h to NSDebug.h. Some of the methods are destined for obsolescence, and some new methods have been added.
* These methods are no longer declared on WindowsTM platforms:
Although they are still declared on WindowsTM, an application should not use the string constants NSFileSystemNumber or NSFileSystemFileNumber, either.
Notes Specific to PDO 4.0 PR1 Developers
Items in the tables below (in the section titled Tables Showing Foundation API Changes) marked with "(P40PR1)" are changes made to Foundation between PDO 4.0 PR1 and OPENSTEP 4.0 and PDO 4.0.
Some additional changes are not contained in the tables or are of particular note:
* The Foundation is now shipped as a shared library in PDO 4.0 for SolarisTM. All applications, tools, frameworks, bundles, libraries, etc. should be recompiled to take advantage of this.
* The size of NSPort and NSRunLoop instances has changed. The NSPort class has become abstract and no longer has any instance variables. Applications, tools, frameworks, bundles, or libraries with subclasses of these two classes must be recompiled.
* The header file NSPosixFileDescriptor.h has been removed from Foundation. This header was NeXT-specific. The header NSFileHandle.h provides portable replacement functionality.
* A few new headers have been added. The API in these headers is not included in the tables below:
* The type of the parameter to NSTask's -setStandardInput:, -setStandardOutput:, and -setStandardError: methods has changed from NSPosixFileDescriptor * to id.
Tables Showing Foundation API Changes
There are four tables that list the API changes between previous versions of Foundation and the version of Foundation in OPENSTEP 4.0. The first table lists general changes to API elements (classes, macros, functions, constants, and so on) except methods, the second table lists the changes to the set of methods offered by the classes in Foundation, the third table lists changes to the return values of methods (for methods that didn't change name, which are listed in the second table), and the fourth table lists changes in the location of declarations. Other miscellaneous changes that weren't described well in table format are given in the sections above.
Changes are noted from the perspective of a developer who used a previous release looking to port their Foundation-based code to OPENSTEP 4.0 (and not through any intermediate releases). For instance, changes that are marked as having been made between OPENSTEP 4.0 PR1 and PR2 do not necessarily apply to NEXTSTEP 3.3 developers (for example, an API might have been added for OPENSTEP 4.0 PR1, but removed for OPENSTEP 4.0 PR2).
The rows in the tables are marked with various symbols in the rightmost column. One set of symbols describes between which releases and OPENSTEP 4.0 the change was made:
SYMBOL MEANING (NS33) Change occurred between NEXTSTEP 3.3 and OPENSTEP 4.0
(EOF11) Change occurred between EOF 1.1 and OPENSTEP 4.0
(40PR1) Change occurred between OPENSTEP 4.0 PR1 and OPENSTEP 4.0
(40PR2) Change occurred between OPENSTEP 4.0 PR2 and OPENSTEP 4.0
The other set of symbols indicate how the API changed. Both NeXT's implementation of Foundation, and the OpenStep specification (since version 1.0 was published) have changed. These symbols attempt to describe what has happened:
SYMBOL MEANING (OpenStep,NeXT) Generically, a change that did not add or remove API, but affects OpenStep and NeXT's implementation
(OpenStep) Generically, a change that did not add or remove API and affects OpenStep, but not NeXT's implementation
(NeXT) Generically, a change that did not add or remove API and affects NeXT's implementation, but not OpenStep
(+OpenStep,+NeXT) Was in neither OpenStep nor NeXT's implementation, now in both
(+OpenStep,NeXT) Was in NeXT's implementation only, now also in OpenStep
(+OpenStep,-NeXT) Was in NeXT's implementation only, now in OpenStep only
(OpenStep,+NeXT) Was in OpenStep only, now also in NeXT's implementation
(OpenStep,-NeXT) Was in both, now in OpenStep only
(-OpenStep,+NeXT) Was in OpenStep only, now in NeXT's implementation only
(-OpenStep,NeXT) Was in both, now in NeXT's implementation only
(-OpenStep,-NeXT) Was in both, now in neither
(+OpenStep) Was in neither OpenStep nor NeXT's implementation, now in OpenStep only
(-OpenStep) Was in OpenStep only, now in neither
(+NeXT) Was in neither OpenStep nor NeXT's implementation, now in NeXT's implementation only
(-NeXT) Was in NeXT's implementation only, now in neither
Occasionally, to the right of the rightmost column is a note for removed API which names the replacement.