TOPIC With every release of its software, NeXT provides notes containing information pertaining to the release. These notes apply to Releases 4.2 and 4.1, and in some cases to earlier releases as well. These on-line Release Notes list new features, fixed bugs, and known bugs that will be of interest to developers using OPENSTEP‰ for Mach, OPENSTEP Enterprise, and PDO. These notes incorporate the latest known information about the release, and are thus more current than those found on the OPENSTEP Enterprise CD-ROM. DISCUSSION
About This Release Release 4.2 is primarily a bug-fix release. In addition, numerous fixes and enhancements have been made to the development tools, and the compilers have been synched-up so that they use the same source base across NeXT's entire product line (OPENSTEP for Mach, OPENSTEP Enterprise, and PDO). Release 4.2 also supports Windows 95 as a deployment platform (debugging is supported, but compilation is not). Windows 95 is not supported for applications that use Apple's WebObjects frameworks, or any other feature of WebObjects not otherwise included in OPENSTEP Enterprise. The various files containing release notes for developers are listed below. These files are included in the ªDeveloper Release Notesº target of the NEXTSTEP Developer bookshelf (in the directory /NextLibrary/Bookshelves), and are located in /NextLibrary/Documentation/NextDev/ReleaseNotes. This file is divided into the following major sections: Installation Upgrading from OPENSTEP 4.1 for Mach Certain hardware configurations appear to cause upgrader to fail (installation hangs, and OPENSTEP is corrupted) when upgrading an OPENSTEP 4.1 system to OPENSTEP 4.2. This issue appears to occur on systems that have EIDE CD-ROM or hard drives, and affects upgrades performed either from a CD-ROM or over a network. It appears that you can work around this issue by placing a disk in the CD-ROM drive before attempting the upgrade. If you encounter this issue, you'll need to install OPENSTEP 4.2 from scratch. This issue does not occur when upgrading from NEXTSTEP 3.3. Installing on Windows 95 While this release of OPENSTEP Enterprise now supports deployment on computers running Windows, 95, these same computers cannot be used to develop OPENSTEP software. (OPENSTEP software developed on Windows NT can be deployed on Windows 95.) See the OPENSTEP Enterprise Installation Guide for instructions on installing the deployment packages (located in the OEDeploy directory on your OPENSTEP Enterprise 4.2 CD-ROM) on computers running either Windows 95 or Windows NT. PDO Installation Due to a possible bug in the SPARC's quad-precision emulation software, this release cannot be used on SPARCstation 5-class machines. Installing on Japanese Language Systems Attempting to do a ªtypicalº installation of the NT Server Deployment (OEMinSys) package on a Japanese language system will cause the installer to enter an infinite loop. If you need to install this package on a Japanese language system, choose "custom" when asked whether you want a ªtypicalº or ªcustomº installation. When presented with the components to install, de-select ªIMEº and proceed with the installation. This issue doesn't arise on non-Japanese systems; nor does it arise when installing either the NT Deployment (OEDeploy) or NT Development (OEDev) packages.
This section lists important issues that were discovered after the CD-ROM was duplicated. Build ing Bundles With PDO on Solaris Although NSBundles now work in PDO 4.2 on Solaris, due to a makefile issue bundles don't build properly (an error occurs when linking). This issue can be fixed by updating bundle.make (in /NextDeveloper/Makefiles/pb_makefiles) and libtool (in /NextDeveloper/bin). New versions of these files can be obtained through NeXTanswers; request NeXTanswer #2499 for the updated files. Compiler This file contains developer release notes for the 4.2 release of the compiler. In the 4.2 OPENSTEP Enterprise, OPENSTEP for Mach, and PDO releases, the compilers on Mach, Windows and PDO are based on the GNU C compiler version 2.7.2.1 and are all built from a single source code base.
Calling superclass methods from within a category (78005)
The -Wmost Compiler Flag
-framework framework-name Search the framework named framework-name when linking. The linker searches a standard set of directories for the framework. It then uses this file as if it had been specified precisely by name. The directories searched by the linker include a couple of standard system directories plus any that you specify with -F. -F directory Add the specified directory to the head of the list of directories to be searched for frameworks. If you use more than one -F option, the directories are scanned in left-to-right order; the standard framework directories (LocalLibrary/Frameworks, followed by /NextLibrary/Frameworks) come after. In your Objective-C code, include framework headers using the following format: #include <framework/include_file.h> Where framework is the name of the framework (such as ªAppKitº or ªFoundationº; don't include the extension) and include_file is the name of the file to be included. If the name of your source file ends in .cc, .cxx, .cpp, or .C, gcc will attempt to compile your program with the C++ compiler. Similarly, if the name of your source file ends in .mm or .M, gcc will attempt to compile your program with the Objective-C++ compiler. The Objective-C++ compiler is now much more useable than the ones included with OPENSTEP for Windows Prerelease 3 and with PDO 4.0. Position-Independent Code Generation (PIC ). The way the compiler generates code has changed. It now generates position-independent code by default when it builds libraries, bundles and executables. You can control the code generation style using the -dynamic and -static compiler flags; -dynamic specifies that position-independent code generation is to be used, whereas -static specifies position-dependent code generation. For related information, see the note on drivers and kernel servers below. C++ Templates . The compiler has been updated to support C++ templates or parametrized types. For example, consider the following code:
#include <stream.h>
Debugging features . The compiler includes a couple new options to assist in debugging. Specify the -H flag on the command to have the compiler emit a listing of included header files (indented to reflect where they are included). Specify the -dM option after the -E (preprocess) option to get a listing of all macros along with their full definitions.
Building drivers and kernel servers . If you are building drivers and kernel servers, be sure to include -static on the command line so that position-dependent code is generated. Compilation with the -dynamic option assumes that the dynamic link editor (/usr/lib/dyld) is present in the running program, and that is not the case for modules to be loaded into the kernel.
Mach programs may need to be recompiled. Since release 4.1 on Mach, libgcc has changed in an incompatible way. It's possible that a small number of existing applications rely on the old libgcc and may crash because of the new libgcc in the base system libraries. We anticipate that this compatibility issue will be resolved in the final version of OPENSTEP 4.2 on Mach; at that time, it may be necessary for you to again recompile anything that now must be recompiled because of this fix. Inline functions may not be properly expanded. In some circumstances, inline C functions and C++ member functions may not be emitted properly, causing assembler errors. You can work around this issue by ordering your inline function or member-function definitions ahead of their references. Passing -fkeep-inline-functions to the compiler also works around this issue, but may sometimes cause other code-generation issues. Keyword-switching for extern "Objective-C" may be delayed. Although keyword-switching is no longer done inside a context tagged by the extern "C" linkage directive, the C++ keywords are turned off inside an extern "Objective-C" { ...} range. When entering and exiting this context, the actual switch in keyword sets may occurs a token or two late, meaning that you may get syntax errors on legal code. For example, if the first token following an extern "Objective-C" range is "class", this will be lexed as an identifier and not the C++ class keyword. You can work around this by re-ordering your declarations or inserting a dummy declaration after a keyword-switching boundary. Link errors on Windows NT (69211). Programs on Windows NT must add explicit references to at least one class in each framework in order to avoid link errors at run time. For instance, you could add a function like that in the following code excerpt, which refers to classes in each of Enterprise Objects Framework's layers. Though never invoked, it forces the appropriate linking to occur.
The -Wno-precomp flag is not supported (63746). The precomp-related options are not yet supported on Windows NT. Constant strings (both char * and NSString) should be 7-bit only. Unless constant strings are 7-bit, your code will be non-portable as compilers will deal with 8-bit strings in a machine-dependent encoding. Objective-C++ global constructors. The Objective-C++ compiler sometimes ignores global constructors; they don't always get called. Random name given to executable by default (66861). If you create an executable and don't use the -o flag to explicitly tell gcc what to name it, gcc will most likely give it a random name. Using pipes to communicate between compiler passes (61306). The -pipe flag doesn't work in the Windows NT compiler. Using -pipe (67853). Although the compiler rarely crashes, if it does, it may generate some assembly language output before doing so. If you use the -pipe flag, the assembler may not be able to detect the fact that its input is incomplete. As a result, the assembler may produce an incomplete, but valid .o file. If you use the make utility to build your application, make will detect the fact that there was an issue during compilation. However, when make is subsequently invoked, it might not recompile the source file that caused the issue, and the linker will most likely complain about unresolved external symbols. ObjC++ requires -lstdc++ when using C++ streams on PDO (69156). When compiling C++ programs that use C++ streams with gcc on PDO platforms, if you specify the -ObjC++ flag you must also specify the -lstdc++ flag. So, for example, a program "foo" that uses cout (and therefore includes iostream.h) would be compiled using gcc as follows: gcc -ObjC++ foo.cc -lstdc++ __declspec(dllexport) __stdcall doesn't work (69194). On Windows NT, functions that are declared as __declspec(dllexport)__stdcall aren't handled properly. This may affect some Windows header files that you include in your programs. The compiler sometimes tries to create a library instead of an executable (69087). This happens on Windows NT when a function is declared as __declspec(dllimport) (perhaps in a header file), but the function is actually defined in the file being compiled. The workaround is to remove the offending __declspec(dllimport). Inconsistent function declarations involving stdcall produce unexpected results (69506). On Windows NT, if a function is forward-declared to be stdcall but not declared to be stdcall in the actual function definition, the compiler will emit code to pop the arguments off the stack, but won't adjust the function name. The linker complains about objects exported as CONSTANT (70212). On Windows NT, if you're building a framework and you create your own DEF file for it, defining exported objects as CONSTANT will produce a warning from the linker advising you to use the word DATA instead. If you substitute the word DATA for CONSTANT in your DEF file, some or all of your objects won't be exported correctly; the linker will be unable to find them. As a workaround, simply leave the declarations CONSTANT and ignore the linker warnings. -static option causes linking to fail (70326). The -static and -dynamic compiler flags are meaningless on Windows NT, and shouldn't be used. Static constructors can't be used for run-time class initialization (54831). The PDO compiler can't apply a user-defined constructor to a global or static C++ object and send an Objective-C message in the same file. To work around this issue, eliminate the constructor, the global, or the Objective-C code. wchar_t string literals (38759). The compiler generates wide-character literals for the host endian-ness only. For example, if you are cross-compiling the string L"x" from m68k to i386, it will be a big endian wide string. The only workaround is not to cross-compile modules which depend on wide characters.
Notes Specific to Release 4.2 New Features There are no new features for the 4.2 release of the compiler tools.
New Features There is only one new feature for the 4.1 release: The dynamic linker now has the environment variable DYLD_FRAMEWORK_PATH to better support the development of frameworks. See the man page for details.
New Features
All object files that are part of a dynamic shared library or that are to be in an executable should be compiled with the -dynamic flag. The -dynamic flag is now the default. Executables using shared libraries must also be linked with this flag when using cc(1) or ld(1) and must be using crt1.o (this is done automatically with cc(1) and the -dynamic flag). To build a dynamic shared library, use libtool(1) with the -dynamic option; typically you also specify the -install_name library_name option as well as other options (see the libtool(1) man page).
The dynamic linker is becoming more fully-featured. It contains some programmatic support for runtime loading (but as of yet no unloading or replacing).
The static link editor uses the symbol tables of dynamically-linked shared libraries to cause modules for undefined symbols to be pulled in from static libraries and to check for undefined symbols. The ld(1) flags for undefined checking -undefined {error, warning, suppress} can be used; the default is to treat undefined symbols as errors. This default holds for dynamically-linked shared libraries and bundles. In these cases the dependent libraries should be listed if available. If not available then -U _symbol or -undefined {warning, suppress} can be used until they are.
The dynamic link editor now has the first level of support for runtime loading. Currently only loading of MH_BUNDLE files is supported. Comments in the header file /NextDeveloper/Headers/mach-o/dyld.h describe what is not yet implemented.
The tool segedit(1) does not have support for dynamic shared libraries.
This document describes how to convert your code from NEXTSTEP Release 3.x to OPENSTEP for Mach Release 4.x.
Release 4.0 is NeXT's first OpenStep-compliant release. OpenStep is an API that enables platform-independent development of client/server applications. The OpenStep API includes the Application Kit, the DPSClient library, and a new kit called the Foundation Framework, which provides an operating system independence layer. The OpenStep Application Kit is functionally equivalent to the NEXTSTEP Release 3 Application Kit, but its API has been reworked to make use of the Foundation Framework. Because Release 4.0 is OpenStep compliant, converting your code to it is a good way to make your application an OpenStep application.
To convert your code, you run a series of scripts. These scripts use tops, a tool that performs in-place substitutions on source files according to a set of rules. The script files contain the rules that tops applies to your code. Most of the scripts are provided in the release, but you must generate some of them before you start converting because they work directly on the custom classes in your code. OPENSTEP for Mach provides a tool that allows you to generate these scripts.
The scripts convert most of the NEXTSTEP API to the new OpenStep API. Some methods, classes, and functions have been altered in such a way that an automated conversion is not possible. For these, the conversion scripts produce an error message that identifies the obsolete code and tells you how to convert it.
You run the conversion in six stages. Each stage runs a different set of scripts. After each stage, you compile your code to identify places where the conversion was not automatic. It is recommended that you run some additional scripts to replace the Common classes with OpenStep API, making your code even more portable.
This document tells you how to set up your project for conversion and how to run the conversion scripts. A separate document, the OpenStep Conversion Guide, describes the changes made during each of the conversion stages and the reason for those changes. Its location on-line is /NextLibrary/Documentation/NextDev/Conversion/ConversionGuide. Read the first chapter of this guide (00_Intro.rtfd) for an overview of the differences between NEXTSTEP 3.X and OpenStep and for a discussion of the different strategies you might use when converting.
1. Convert your project to a 4.0 project. 2. Generate the conversion scripts. 3. Run the six-stage conversion process and any optional conversions. 4. Convert your nib files. 5. Debug your application.
These steps are described further below.
1. Read OPENSTEP Development: Tools and Techniques and the release notes for Project Builder and Interface Builder to learn about changes to the environment.
The document you are reading now does not describe how to use the new Project Builder. The book OPENSTEP Development: Tools and Techniques is on-line in the directory /NextLibrary/Documentation/NextDev/TasksAndConcepts/DevGuide. The release notes are in the directory /NextLibrary/Documentation/NextDev/ReleaseNotes.
2. Make sure your code compiles cleanly without warnings.
Perform this step so that any warnings that show up during conversion won't become mixed in with pre-existing warnings. Make sure the -Wall compiler option is being used.
Before you compile your 3.3 code on a 4.0 system, you need to change the search path for header files to the directory /NextDeveloper/OpenStepConversion/3.3Headers. To do this in the new Project Builder:
1. Choose Inspector from the Tools menu to bring up the project inspector. 2. From the inspector pop-up list, choose Build Attributes. 3. Choose Header Search Order from the pop-up list in the Build Attributes inspector. 4. Type /NextDeveloper/OpenStepConversion/3.3Headers and click Add.
3. Back up your project directory.
The conversion scripts modify your code in-place, and they do not create backups for you. It is strongly recommended that you back up your project after each conversion stage in addition to backing up before you begin, provided you have enough space.
4. Delete the NeXT-provided libraries (such as libNext) from your project, and add the corresponding frameworks (such as /NextLibrary/Frameworks/AppKit.framework).
All NeXT-provided libraries are replaced with frameworks in 4.0. A frameworks' executable code is a dynamic shared library. To add the Application Kit framework, in Project Builder choose Add File from the Project menu, select /NextLibrary/Frameworks/AppKit.framework from the Add File panel, and choose Frameworks from the file type pop-up list on the Add File panel. Add the Foundation Framework in the same way.
Frameworks are bundled differently than shared libraries. All of the support files for a framework are contained in the same directory, so you no longer have to know that the library itself resides in one place, its header files another place, and its documentation still a third place.
When you add a framework to your project, it doesn't appear in the Libraries suitcase. Instead, it appears in the Frameworks suitcase. You are able to see that framework's header files and documentation underneath that suitcase.
5. Change the application class in Project Builder.
In OpenStep, all keywords are prefixed with "NS", so the Application class is now NSApplication. If you are converting an application project, you need to change the class in Project Builder so that it will use the appropriate class when updating your main function. To do this, bring up the project inspector by choosing Inspector from the Tools menu. In the inspector, choose Project Attributes. Finally, type NSApplication in the field labelled Application Class.
6. Convert your makefiles.
The new Project Builder comes with new Makefile.postamble and Makefile.preamble files. Convert your preamble and postamble files if you performed some customization on them. You can find copies of the new templates in the directory /NextDeveloper/Makefiles/project. Rename your existing preamble and postamble files, copy the new templates into your project directory, rename the template (remove the .template extension), and merge any customizations you would like to keep into the new templates.
Most of the changes to the makefiles are additions made to support frameworks, however some makefile variables are now obsolete. The additions are documented in the comments in the preamble and postamble files. The following table lists the obsolete makefile variables and what you should use as a replacement.
BUNDLELDFLAGS OTHER_LDFLAGS PALLETTELDFLAGS OTHER_LDFLAGS COMMON_CFLAGS OPTIMIZATION_CFLAG, WARNING_CFLAGS NORMAL_CFLAGS OPTIMIZATION_CFLAG, WARNING_CFLAGS DEBUG_CFLAGS Use DEBUG_BUILD_CFLAGS. PROFILE_CFLAGS Use PROFILE_BUILD_CFLAGS. DYLD_APP_STRIP_OPTS LIBRARY_STRIP_OPTS (-S by default) RELOCATABLE_STRIP_OPTS DYNAMIC_STRIP_OPTS (-S by default) OTHER_DEBUG_LIBS Add libraries using Project Builder. OTHER_PROFILE_LIBS Add libraries using Project Builder. OTHER_JAPANESE_DEBUG_LIB Add libraries using Project Builder. OTHER_JAPANESE_PROFILE_LIBS Add libraries using Project Builder. BUNDLE_LIBS Add libraries using Project Builder. PRECOMPS Use Project Builder Inspector to mark headers for precompiling. In addition, the following are some other changes to makefiles of which you should be aware: Generating the Conversion Scripts
To generate conversion scripts, do the following:
1. Add /NextDeveloper/OpenStepConversion/UtilityScripts/shellscripts to your PATH environment variable. The convert command, which you use to convert your code, is in this directory.
2. In a Terminal window, enter these commands to create files that will be used to generate the conversion scripts:
% cd project_directory % convert -preprocess
3. Modify the files StringMethods, StringDefines, RectMethods, and VoidMethods, which are used to generate the conversion scripts. Carefully read "Modifying the Files Used to Generate Conversion Scripts" below for instructions on how to do this. Once you perform step 4, you cannot return to this step.
WARNING: Do not move on to step 4 until you have fully completed step 3.
4. Generate the optional conversion scripts with this command:
% convert -makescripts
File Description ClassHierarchy1 Describes the class hierarchy before conversion in a format tops can understand. ClassHierarchy2 Describes the class hierarchy after conversion in a format tops can understand. StringMethods Lists methods that have (char *) or (const char *) as either a parameter type or return type. StringDefines Lists #defines that were determined to be of type (const char *). RectMethods Lists methods that use pointers to NXRects, NXSizes, or NXPoints as either a parameter or a return type. VoidMethods Lists methods that did not specify a return type. In order to generate conversion scripts that will convert your code properly, you need to modify all of the files produced by convert -preprocess except the class hierarchy files. The following sections provide instructions on this step. After you modify these files and run convert -makescripts, some additional conversion scripts appear in the CONVERSION directory. These scripts are executed during the conversion process.
The StringMethods file contains a list of every method in your application that takes a C string as an argument or returns a C string. It does not list overrides of Application Kit methods; those are taken care of by the conversion scripts provided in the release. All of the methods listed in this file will have their C string arguments and return values converted to NSStrings. Only methods that don't modify the string should have their C strings converted. Look at the implementation of every method listed in the StringMethods file. If the method modifies its C strings, remove its name from the file. To skip the optional conversion of C strings to NSStrings entirely, delete all of the methods from this file. (You may want to save them in a different file.) Before you decide, you may want to read about the conversion of C strings to NSStrings in the OpenStep Conversion Guide. See the chapter "Converting the Common Classes." You can locate a method's implementation easily in Project Builder by doing the following (for more information, see the development environment release notes):
1. Choose Find from the Tools menu to display the Project Find panel. 2. In the Project Find panel, enter the name of the method in the text field. 3. Make sure Definition is selected in the pop-up list. 4. Click the Find button.
StringDefines
The RectMethods file contains a list of every one of your application's methods that takes a pointer to an NXRect, NXSize, or NXPoint structure or returns a pointer to one of these structures. (It does not list overrides of Application Kit methods.) All of the methods listed in this file will have their structure pointer arguments and return values converted to the actual structure.
Only methods that don't modify the structures should have their arguments and return types modified. Look at the implementation of every method listed in the RectMethods file. If the method modifies an NXRect, NXPoint, or NXSize structure, remove its name from the file. To skip the optional conversion of structure pointers entirely, delete all of the methods from this file. (You may want to save them in a different file.) Before you decide, you may want to read about the NXRect, NXPoint, and NXSize conversions in the OpenStep Conversion Guide. See the chapter "Converting the Common Classes."
Look at both the implementation and the uses of each of the methods listed in the VoidMethods file and perform the action listed below. (To look at all of the uses of a method, enter its name in Project Builder's Project Find panel, choose References from the pop-up list, and click Find. The bottom half of the Find panel lists all of the places the method is invoked.)
For example, consider the methods shown in the following code fragment. All of these methods except newCount would be listed in the VoidMethods file because they don't specify a return type. However, the countingObject method has a meaningful return value because countSomething expects it to return an object. countSomething is is the only method that should truly be converted to return void because it is invoked as if it already did return void. Thus, in the VoidMethods file, you would delete countingObject but leave countSomething.
1. Back up the project directory.
2. In Project Builder, close all of the source files.
The convert script, which you run in the next step, changes your source files. If you have looked at these same source files in Project Builder before you run the script, the file displayed by Project Builder won't reflect the changes that convert makes. To make sure that you are always looking at the latest version of your files, close all of the files in Project Builder before you run the script.
You can see which files you have loaded in Project Builder using the Loaded Files panel. Choose Loaded Files from the Tools menu to bring up the Loaded Files panel. Select a file in the Loaded Files panel, then choose Close from the File menu to close it.
If you don't perform this step, convert will still work properly, but when you look at the source files after it is complete, they won't reflect the changes. To see the changes that convert made, press Command-u.
3. In a Terminal window, enter:
% cd project_directory % convert -stagex
where x is the number (1 through 6) of the conversion stage you want to perform. If you don't specify source files on the command line, they will be identified with the pattern:
*.[hcmCM] *.psw* *.*proj/*.[hcmCM] *.*proj/*.psw*
In other words, all code files in your current directory and in the first level of subproject directories will be converted. If this is not sufficient, specify the appropriate file list after the -stage option:
convert -stagex file1 file2 ...
Each conversion stage takes several minutes to complete. Stage 1 is the longest stage.
WARNING: The conversion scripts should not be run out of order, and it is not recommended that they be run on the same file more than once. In general, it's a good idea to save a copy of your files after each stage.
4. Once the conversion is complete, use FileMerge to compare your project with the backup of your project. This is a good way to learn about the differences between NEXTSTEP and OpenStep. (To learn how to use FileMerge, see the development environment release notes.)
5. Open the project in Project Builder and use the Inspector panel to add /NextDeveloper/OpenStepConversion/IntermediateFrameworksx to the search path for frameworks, where x is the number of the conversion stage. (For stages 2 through 6, remove the IntermediateFrameworks directory for the previous step.)
In Project Builder, you change the search paths for frameworks from the Build Options inspector. Choose Inspector from the Tools menu to bring up the inspector panel, and choose Build Options from the inspector's pop-up list. In the Build Options inspector, there is another pop-up list. Choose Framework Search Order from that list. Type the new search path for frameworks, then click Add.
In between the first conversion stage and the last conversion stage, your code is in an interim state and will not compile successfully with either the NEXTSTEP 3.X headers or the OPENSTEP for MachOS Release 4.0 headers. The IntermediateFrameworks directories have NEXTSTEP headers at the intermediate stages of conversion so that your code will compile. Your code will not link successfully until after the sixth stage.
There is no IntermediateFrameworks directory for stage 6. After stage 6, you should use the default search path for frameworks (/NextLibrary/Frameworks).
NOTE: Be sure you change the Framework Search Order, not the Header Search Order.
7. Build your project and work through any error messages.
The conversion process places #error messages in places where automated conversion was not possible and #warning messages in places where the conversion might not be correct. You will see these messages when you compile. Once your code compiles successfully, back up your project again, and run the next stage.
If you need help deciding how to correct an error, see the OpenStep Conversion Guide. It describes how to correct most of the errors that occur. If you need more information about a particular class or function, look in the Foundation Framework Reference in /NextLibrary/Frameworks/Foundation.framework/Resources/English.lproj/Documentation or the Application Kit Reference in /NextLibrary/Frameworks/Foundation.framework/Resources/English.lproj/Documentation. If the class has no documentation yet, see the OpenStep Specification in /NextLibrary/Documentation/OpenStepSpec.
NOTE: If Project Builder is not showing you the updated source files (the source code does not match the warning you see), type Command-u. Be sure to close all files in Project Builder as described in Step 3 before you run the next conversion stage.
You may want to set the Continue After Error preference to Project Builder. If you do, Project Builder will continue to build even after it finds an error. You can find the Continue After Error preference in the Preferences panel, under Build.
8. If you're converting an application project, convert your nib files. To do this, use this command: % convert -nib
convert -all
This command runs all six conversion stages one by one, then converts any nib files. Before you enter this command, you still must generate the conversion scripts for the project as described earlier in this document. Remember to be very careful when modifying the files used to generate the conversion scripts. It will save you time in the end.
Conversion Script Purposes CustomIBAPI.tops Converts Interface Builder API for palettes. ListToMutableArray.tops Converts List objects. HashAndStringTableConversion.tops Converts HashTable and NXStringTable objects. StringConversion2.tops Converts more C strings to NSStrings. StreamToMutableData.tops Converts streams to NSMutableData objects. StreamToString.tops Converts streams to NSString objects. TableView.tops Converts NXTableView objects to NSTableView objects. VMConversion.tops Converts MachOS virtual memory functions to Foundation functions.
To run a single script on your source code, use this command:
tops -scriptfile scriptFile *.[hcmCM] *.psw* *.*proj/*.[hcmCM] *.*proj/*.psw*
Where scriptFile is the complete path for the script (/NextDeveloper/OpenStepConversion/ConversionScripts/scriptName). See the OpenStep Conversion Guide for information on these scripts.
NOTE: Because the API changes between C strings and NSStrings and between NXTableViews and NSTableViews are significant, the usefulness of the scripts StringConversion2.tops and TableView.tops vary. You may want to run them on a copy of your code first to see if they help you.
Debugging symbols for dynamic shared libraries are not present in the program itself. GDB obtains them when the running program attaches and links to the shared library. This means that before the program is actually running, GDB has no information about the contents of the dynamic shared libraries that it uses.
Because of this, it is not possible to set ordinary breakpoints in a shared library before that library has been attached. GDB provides a new command for this purpose, future-break or fb. If GDB cannot find the necessary symbols to resolve a future-break command, it defers the breakpoint and attempts to resolve it later, when new symbols from a shared library become available. Caveat: since the future-break command deals with names and symbols that are as yet unknown to the debugger, it cannot check spelling for you; if you make a spelling mistake, it will never be detected and the breakpoint will never take effect.
There is also an environment variable, DYLD_LIBRARY_PATH, which tells the dynamic link-editor where to search for dynamic libraries. This variable can be used to cause a library with debugging symbols to be linked, even though the library on the default path has no symbols. This environment can be set from within GDB by using the setenv command. In order to affect the program being debugged, it should be set before running the program.
More generally, when debugging a program that uses multiple threads it's possible to create a situation in which a deadlock will occur. Whenever the next or step commands are issued, GDB lets only the thread being debugged to execute. All other threads are suspended until the command is completed. Therefore, if you attempt to step over a line of code which tries to communicate with another thread, the program will deadlock.
To deal with issues like this, a "run-all-threads" option has been added to GDB. This controls whether or not all of the threads should execute while single-stepping. The default value for this option is "off", meaning the behavior is the same as in OPENSTEP 4.1. In order to prevent a deadlock like that described above, issue the following command in GDB:
set run-all-threads on
We recommend that you use this option only if you're experiencing a deadlock. Allowing other threads to execute while stepping through code can produce confusing results if, for example, the other threads may be changing the values of global data.
Debugging symbols for dynamically-loaded libraries are not present in the program itself. GDB obtains them when the running program attaches and links to the DLL. This means that before the program is actually running, GDB has no information about the contents of the DLLs that the program uses.
Because of this, it's not possible to set breakpoints or access data in a DLL before the DLL has been attached by the program. GDB provides a new command for this purpose, future-break or fb. If GDB cannot find the necessary symbols to resolve a future-break command, it defers the breakpoint and attempts to resolve it later, when new symbols from a shared library become available. Caveat: since the future-break command deals with names and symbols that are as yet unknown to the debugger, it cannot check spelling for you; if you make a spelling mistake, it will never be detected and the breakpoint will never take effect.
· 0x30001000 System · 0x31001000 nextpdo · 0x32011000 Foundation · 0x34021000 AppKit · 0x38031000 NeXTApps · 0x3A041000 DevKit · 0x3C051000 ProjectBuilder · 0x3C051000 InterfaceBuilder · 0x40001000 Message · 0x42011000 WebObjects · 0x44021000 EOControl · 0x46031000 EOAccess · 0x48041000 EOInterface · 0x4A051000 Sybase · 0x4C061000 Oracle · 0x4E071000 Informix · 0x50081000 nextorb · 0x52091000 EOModeler
(gdb) print [myClass showValue: 12]
If the method comes from a Category, you must include the category name, like this:
(gdb) print [myClass(myCategory) showValue: 12]
(gdb) list +[myClass init] (gdb) break -[myClass(myCategory) showValue]
You can also set breakpoints or list a method just by giving a selector. If the selector is implemented by more than one class, gdb will list the corresponding methods and ask you to choose one or more:
(gdb) break init [0] cancel [1] all [2] -[Change init] at Change.m:20 [3] -[DrawApp init] at DrawApp.m:130 [4] -[Graphic init] at Graphic.m:139 >
You would then enter your choice or choices at the ">" prompt.
(gdb) info classes ^NS
To learn about selectors, you can use the info selectors command. To find every selector containing the string "withObject:" you could enter:
(gdb) info selector withObject:
To learn about methods, you can use the info function command, which also takes a regular expression. Since the square bracket characters `[' and `]' are significant in regular expressions, you can quote them with a backward slash to prevent their being treated as special characters. To list all the methods of a class, you might say:
(gdb) info function \[MyClass
To list all the methods whose selector ends with ªcount:º, you might say:
(gdb) info function count:\]
If you want to know about a specific method of a specific class, but you are not sure if it belongs to a category, you could use the ª.*º wildcard sequence to stand for ªany number of any charactersº:
(gdb) info function MyClass.*mySelector:
When you switch threads, you will frequently find yourself in a non-debuggable area of code from which you cannot even get a backtrace. See the section on known issues, ªNon-Debuggable Codeº below.
In NEXTSTEP Release 3.3, as well as in prior releases, all developer documentation was located in a subdirectory of /NextDeveloper/Documentation/NextDev. In OPENSTEP 4.2, framework documentation has been moved to a location inside of the relevant framework. All remaining developer documentation can still be found under /NextDeveloper/Documentation/NextDev.
Driver Development
In keeping with the philosophy that all framework resources be located within the framework, framework reference documents are located in the directory Resources/English.lproj/Documentation, relative to the ª.frameworkº directory. So, for instance, reference documentation for the Application Kit Framework can be found in /NextLibrary/Frameworks/AppKit.framework/Resources/
English.lproj/Documentation
.
This document lists all of the API changes and some of the bug fixes relating to the NeXT ORB for this release.
protocol:(NSString *)proto host:(NSString *)hostName
you can now use:
-(id)OLEObjectWithRegisteredName:(NSString *)name localeId:(unsigned long)localeId host:(NSString *)hostName
From Visual Basic, the alternative to this standard call:
orb.connectTo(name, protocol, host)
is:
orb.connectUsingOLE(name, localeId, host)
In the above, the localeId arguments are Win32 LCID's: 4-byte quantities which specify a primary language and sublanguage. (For more details see the Microsoft Win32 SDK documentation.) Common values are 0x9, for ªneutralº English, or 0x409 for North American English.
These new methods set the locale for the returned object. Also, the locale propagates recursively to all objects returned from that one.
For the 2.0 release notes (which include a lot of information that's still relevant for 2.1), see NeXTanswer #2455. If you have access to the World Wide Web, you can look up the URL http://www.next.com/NeXTanswers/HTMLFiles/2455.htmld/2455.html .
The documentation supplied with this release is 2.0 documentation. The 2.1 documentation will be made available when the product is released.
The MachOS version of this release is 3-way fat; it can be used to develop software for NeXT, Intel, and SPARC. The OpenStep for Windows version of this release can be used to develop software for Intel machines running Windows NT.
Installing the Examples
Note: When installing the examples for use with the Informix adaptor, use EOModeler's Connection Dictionary Inspector to set "databaseEncoding" to "Non-lossy ASCII" for the Movies and Rentals models. This will allow Enterprise Objects Framework to insert records with non-English characters.
Depending on your desired setup, you use the tools available with your database server to set up one or two new user/databases. For example. on Sybase you might create a new database on your server called ªMoviesº and login with the user ªsaº. On Oracle you might create a new user with the name ªMoviesº. Once you have set up these accounts, you're ready to install the examples.
Note: The /LocalDeveloper/Frameworks directory must be created and writable by you in order to build the examples. On Mach this can be accomplished by using su to become the superuser and then executing the following commands: mkdirs /LocalDeveloper/Frameworks chmod a+w /LocalDeveloper/Frameworks
1700 NW 167th Place Beaverton, OR 97006
1-800-547-4000 (General Phone) 1-800-443-1601 (Tech Support Phone) 1-503-645-6260 (Tech Support Fax)
pvcs_answerline@intersolv.com
Support is planned for other popular SCM products that are accessible from Mach or Windows. Please contact NeXT Product Marketing regarding future plans and schedules of SCM integrations with Project Builder.
The following default should either be YES or NO, depending on whether or not you want to lock files automatically when you start to edit them in Project Builder.
defaults write ProjectBuilder lockOnEdit YES_or_NO
Some operations, such as creating a new repository or importing a project into it for the first time, must be performed using tools provided by the underlying SCM system.
OPENSTEP 4.2 PVCS Adaptor Bundle User's Guide
Overview
Before you begin...
Note: When creating a repository with PVCS, using the "Project Assistant" is recommended. When prompted to add directories to the repository, make sure you "Add with Subdirs..." in order to incorporate all of the subdirectories in your project.
Show Panel Displays the SCM Panel. Show Console Displays the SCM Console. Create Work Directory Displays the Create Work Directory panel. Merge Files Puts all project files into the SCM Panel and selects SCM's Merge operation in the panel. Stamp Files Puts all project files into the SCM Panel and selects SCM's Stamp operation in the panel. Check In Files Puts all project files into the SCM Panel and selects SCM's Check-In operation in the panel.
File-->SCM Show Panel Displays the SCM Panel. Check In Files Puts files selected in ProjectBuilder into SCM Panel and selects SCM's Check-In operation in the panel. Lock Files Puts files selected in ProjectBuilder into SCM Panel and selects SCM's Lock operation in the panel. Unlock Files Puts files selected in ProjectBuilder into SCM Panel and selects SCM's Unlock operation in the panel. Stamp Files Puts files selected in ProjectBuilder into SCM Panel and selects SCM's Stamp operation in the panel. Show Changes Diff's the files selected in ProjectBuilder with their corresponding repository head versions.
SCM Panel
- Table View - Update Status Button - File Status Filter - Miscellaneous Operation Buttons - Core Operations Popup Button
- SCM console - Log Entry Panels
- Creating a New Work Directory - Adding/Removing Files in the Work Area - Locking/Unlocking Files - Checking In Changes - Stamping Files - Merging the Work Area - Miscellaneous Operations
- Display Create Work Directory Panel - Set Work Directory and Repository Location - Create and Open New Project
When removing a file from the project, SCM immediately removes that file from the list it maintains and there is no need to commit the operation to the repository. Under PVCS files are never actually removed from the repository (they'll only be removed from the PB.project).
1. Select the files and then "Unlock" them using the SCM panel operation. 2. Check-In the desired locked files - if the check-in is successful the files will automatically be unlocked.
Checking in Changes
- Identify and Verify Modified Files - Execute Check-In Operation
Issue: File and Project RENAME not supported
Description: Renaming files or projects under SCM control is not supported. Attempting to do so will result in a confused SCM state.
Reference: 1647
Issue: Checking in files sometimes makes them write protected
Description: Occasionally the user may be prompted to overwrite a read-only file or revert a file to saved. These alerts occur mainly because the revision control system is writing to the files without Project Builder's knowledge. In general it is acceptable to revert or overwrite the files and continue working. This issue will be fixed in the next release.
Issue: Updating a file that has been added (but not committed) changes status to up-to-date
Description: If a file is added to a project and then updated before it is checked in, the file status is incorrectly changed to "Up-To-Date" instead of remaining "Added".
Workaround: Check-in added files before you perform any other SCM operations on them.
Reference: 1606
Issue: If there is a lock on the repository SCM will hang forever
Description: If there is a lock on the CVS repository, the SCM adaptor (and hence Project Builder) will hang indefinitely.
Workaround: Manually remove the lock from the CVS repository and restart Project Builder if necessary._
· "Wrap to Page" mode. This mode causes the document to be wrapped to the current page size (as opposed to the window size), and thus shows you a simple WYSIWYG representation of your pages. This mode also allows zooming.
· Support for new text object features such as hyphenation, kerning, ligatures, and baseline offsets.
· Ability to read/write plain text files in different 8-bit character encodings and Unicode. Coupled with the Kanji support in the new text object, you can read/write/edit Kanji files created by 3.3J or 4.1J. (You will need Kanji fonts and input manager.)
The alternate encoding to apply to a file is specified by a popup in the Open or Save panels. The default item, "Default," tells TextEdit to use either the default 8-bit encoding of the system or Unicode. Other choices let you select different encodings. You can also set the default setting of this popup via the Preferences panel.
Sources to TextEdit are available with the developer software, in /NextDeveloper/Examples/AppKit/TextEdit.
Issue: Encoding popup in Open/Save panels not available under NT3.51
Description: Because accessory views aren't supported under NT3.51, there is no encoding popup in the Open/Save panels.
Workaround: You can use the popup in the Preferences panel to set the default choice for the popup, which will then be used when files are opened or saved.
In addition, please refer to the Application Kit release notes for the new text system bugs. |
||||||
| Document Information | |
| Product Area: | Apple Software |
| Category: | OPENSTEP |
| Sub Category: | Release Notes |
Copyright © 2000 Apple Computer, Inc. All rights reserved.