@(#) LSARC Questions Version 2.0u @(#)20q-new.txt 1.5 07/12/07 __________________________________________________________________ Copyright 2007 Sun Microsystems, Inc. #ifdef REMOVE If your materials contain any information that should not be made publicly available, you must add appropriate notice to them as defined in Sun's Information Protection Policies, as described at http://sunwebcms.central.sun.com:8001/sunweb/cda/mainAssembly/0,2685,369800_3075_5762407,00.html #ifdef ADVICE There are logically 3 documents here: 1. Background info (mostly in the intro and some of inline, #ifdef ADVICE). 2. The questionnaire itself. Consider it "Things to Specify if Applicable." 3. Other Considerations (mostly at the end, #ifdef ADVICE). The last of these might be a separate document, but is here to ease editing and review. Our advice is only that; if you have reasons to deviate from our advice, discuss that with the ARC in your materials and during your review. #endif INTRODUCTION: Here is a comprehensive list of questions that LSARC asks of project presenters. Ideally, all this information would already be in the specifications that tell engineers what to implement, testers what to test, and management what the project entails, so they can schedule resources. The http://sac.eng.sun.com/HTML/FuncSpec.html template may therefore substitute for this questionnaire, if it sufficiently addresses every applicable aspect. Even a functional spec follwing the PLC template may substitute, though due to the hardware orientation of that template it's less likely that all the issues the ARC cares about will be addressed. Before submitting a PLC-template function spec, please read through these questions and ensure all applicable ones are addressed in the spec. PLEASE PROVIDE POINTERS: On this questionnaire, tell which sections of of the specifications provide which answers. There is no need to duplicate text, but don't forget to submit the specifications on-line for archive and review purposes. Any answers not explicit in the project specifications may be provided here. MECHANICS: Please add any answers and return this questionnaire in ASCII to ease searching, reading remotely, and quoting in E-mail. Start each answer flush left, and keep lines < 80 columns. (The tables may be in separate files, and should be, if they have to be wider. Diagrams may be separate files, but in any case must be printable on Solaris; see Q20.2.) SHRINK-TO-FIT: Not every question will pertain to every project, nor will be a significant consideration for that project. Tell us which questions you deem inapplicable, so we can tell they weren't merely neglected. If an entire set of questions is inapplicable to this project, note "N/A" for the main question and delete subordinate questions. #ifdef WINDOWS The full Questionnaire also includes questions for projects with Microsoft Windows components (#ifdef WINDOWS), based on 1.2PC 7/12/95. Some section numbers append W for Windows or S for Solaris, Linux, and other Unixes, to differentiate if both are answered. If your project does not include Windows components, you may use /usr/ccs/bin/unifdef -t -UWINDOWS as a filter to remove the Microsoft Windows questions. #endif An ARC member will be named "owner" of the case at the end of the project's pre-inception discussion, if not sooner. You may ask that member (or the Chair) for help interpreting these questions or their relevance to your project. Sections 9 through 17 address the details of a project's environment, interfaces, and so forth; it is understood that many of these issues will be unresolved at the time of an inception review. They must, however, be answerable at commitment review, and should be addressed to the extent possible at inception review. You may present this information in any order or form that seems appropriate. An introduction to the ARC review process is in http://sac.eng.sun.com/arc/ Projects that are modifying existing, ARC-approved projects should review the former ARC opinion and materials, and not restate what is identical about the projects; limit discussion to what is new -- being dropped, replaced, changed, or extended -- and describe the outcome of advice on the previous projects' opinions. If a previous release exists, but was unapproved, the committee needs proposed stability classification and specifications of *all* the product or project's interfaces. Also describe the differences proposed, and the migration plan (e.g., backwards-compatibility features, translating former configuration files). Use an Inception Review to validate your approach, identify likely issues, and determine what information will be needed to achieve Commitment. Answer "UNKNOWN" (not N/A) if the information might be known (and applicable) later. Answer Question #9 thoroughly before Commitment Review. Projects cannot be approved until this information is complete. If the project has too much to describe all at once, it is probably too much to review all at once; discuss with your case owner subdividing the review into multiple meetings, and perhaps even separate projects of a common "program". If this project has had a Review and is returning for another review, clearly mark any new or changed material with a date, change bars, or whatever. #endif /* REMOVE the above; '/usr/ccs/bin/unifdef -t -UREMOVE' can do it. */ __________________________________________________________________ 0. Remind us: 0.1 The case number for this project? ??ARC 200x/xxx 0.2 This questionnaire is for an [ ] Inception Review or [ ] Commitment Review 0.3 Name(s) of person(s) answering the questions? 0.4 Are these case materials considered public or con- fidential? 1. What specifically is the proposal that we are reviewing? 1.1 The case owner will need to put a 1 to 4 paragraph description at the top of the Opinion document. Suggest text for it. Please be specific about deliverable components and their interfaces. #ifdef ADVICE An example summary may be found in the opinion.* files in http://sac.eng.sun.com/PSARC/1995/224/ #endif 1.2 Is this a new product, or a change to a pre-existing one? If it is a change, would you consider it a "major", "minor", "micro" or "patch" change and why? (See the release type definitions in http://sac.eng.sun.com/BestPractices/release_taxonomy.html ) 2. What is the motivation for it? What are the expected benefits for Sun? By what criteria will you judge its success? 3. The plan: 3.1 Who (what groups in what business units) are working on it? 3.2 What is the current status? 3.3 Has a design review been done? #ifdef ADVICE (Note that LSARC is not a design review service, but an architecture/interface review board; ARC members may be invited to design reviews, however.) #endif 3.4 What Product Approval Committee (PAC) do you expect to approve this project? #ifdef ADVICE PACs are listed on the Sun Product Life Cycle (PLC) site http://sunplc.central.sun.com/plcpmoweb/contacts/contacts.html #endif 4. Related Projects: 4.1 What not-yet-delivered Sun projects (libraries, hardware, etc.) does this project depend upon (i.e., need to be successful)? 4.2 What non-Sun projects does this project depend upon? 4.3 What other projects depend on this one? 4.4 What other active projects at Sun are related to your project, and how are they related? 4.5 What future projects should be started or avoided to help your project succeed, and why? 4.6 What open source communities does this project interact with? 5. What technical approach has been selected by the project? #ifdef ADVICE This is an open-ended question seeking an implementation overview. Answers might cover: * a "make versus buy" decision; * a client/server or multi-level model, and the determination of the boundaries between the components; * CASE tools, if the choice restricts capabilities; * implementing some project-specific service rather than using or extending a generic system service; * other approaches that are more common or arguably superior. Case materials must distinguish this project (which is subject for approval now) from wishes, hopes or plans, though it's fine to outline possibilities for future evolution. #endif 6. How is the project delivered into the system? Is it bundled or unbundled? What are your delivery vehicles (WOS, CTEAM...) Identify package abbreviations, directory names, library names, databases, etc. #ifdef WINDOWS For Microsoft Windows components, name the DLLs, VxDs, etc. In this list, highlight any components (executables, libraries, etc.) which require special consideration at installation time. For example, if the project installs a third-party library, what provisions are made for handling version mismatches with any previously-installed copies merging of new database entries? #endif 7. Hardware Platform Dependencies: 7.1 What are the project's hardware platform dependencies, including Sun or third-party add-on hardware that is explicitly supported. 7.2 Are Solaris components expected to work on SPARC and x86? If not, why? What will be affected in porting? Any problems if porting to another architecture were desirable? 7.3 Are there issues with "binary" interfaces, which would be incompatible on various instruction set architectures? #ifdef WINDOWS 7.4W For Microsoft Windows components, what is the minimal hardware configuration supported (e.g., Pentium with 128mb of memory)? #endif 8. Compatibility and Interoperability (Consider a compatibility matrix, if the information is nontrivial.) #ifdef WINDOWS 8.1W For Microsoft Windows components, what Windows releases does it work on? Client-oriented releases (98/ME/XP/Vista)? Server releases (2000/2003)? 8.2W Does it depend on features and software that exist only in certain versions of Windows, such as networking features not in XP Home? #else 8.1S OS compatibility: 8.1.1 For Solaris components, what Solaris release(s) does it run on or work with? 8.1.2 Does it run on Linux? What distribution(s) and version(s)? 8.1.3 Might the project need any extra adaptation to work successfully with future (i.e., later) releases? patches? 8.2S Do Solaris components depend on OS features not in the core OS (e.g. Berkeley compatibility package, /usr/ccs, /usr/ucblib, optional loadable kernel modules)? What packages or clusters must be installed first (if the "core" set of packages is insufficient)? Do the packages express those dependencies explicitly? 8.3 Do Solaris components use any system interfaces, commands, or features not in POSIX or the Single Unix Specification? What is the minimum version of those standards required? (POSIX.1-1990, UNIX98, UNIX2003?) #ifdef ADVICE Read "man standards" for what those abbreviations mean. Projects using system (or other project) interfaces that are not Committed (formerly Public, Stable, or Standard) should explain to the ARC why the risk of being broken by an incompatible change is sufficiently low, and how the risk will be managed. One way to verify interface usage is to review "ABI application certification" results for all executables and libraries that run on Solaris. See http://www.sun.com/developers/tools/appcert . #endif 8.4 Do Linux components use any interfaces, commands, or features not in the Linux System Base? What is the minimum LSB version required? #ifdef ADVICE http://www.linuxbase.org/ #endif #endif /* WINDOWS */ 8.4 With what releases of what other projects or products does this project interoperate? Using what interfaces? (Provide reference to ARC case approving these interfaces or a specification and proposed stability classification for the interfaces.) 8.5 What internationalization (I18n) issues are involved? What languages *can* be supported by localization without modifying the base product, whether or not a localization is currently planned? What I18N interfaces will the project adhere to? If strings are used, how are they accessed -- Solaris-mostly gettext(), X/Open catgets(), GNU gettext? What items and interfaces are (or are not) being internationalized? #ifdef ADVICE See the Internationalization Best Practice document. http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=I18N.bp #endif 8.6 Are there any existing or proposed standards it conforms to or deviates from? Examples: SPARC/x86 ABI, POSIX, Open Group standards, IETF RFCs, national or international standards. Include version numbers where applicable. 8.7 Can this version co-exist or interoperate with earlier and later versions? with alternative implementations (perhaps by other vendors)? Is switching between installed versions or implementations possible? What is involved? 8.8 Does the project move, disable, delete, circumvent or change any files, components, or services outside the project? 8.9 Does it use any interfaces (for example, a driver using kernel structures) that are private to another consolidation? read or write /dev/kmem? trap directly into the kernel, instead of via libc functions? #ifdef ADVICE These are all serious architectural issues, and will need justification and discussion. #endif 8.10 What components (e.g., libraries or packages) are shared with other projects or products? 8.11 Can customization (e.g., OEM relabeling) be accomplished via resource files that are separable from the source code? 8.12 Device Drivers: 8.12.1 Does this project deliver any device drivers? 8.12.2 Does it conform to the Solaris DDI/DKI (manual sections 9e, 9f, & 9s)? 8.12.3 Does it pass "DDICT" DDI compliance tool (available on Solaris DDK)? 9. Technical Content 9.1 Architecture Diagram: Include in case materials an Architecture Diagram, showing the major components, major interfaces, and all customer-visible interfaces and inter-project interfaces. Give each a number or brief name for use in the Interface Table below. #ifdef ADVICE The ARC definition of "interface" is broad -- any syntax or semantics that anything outside your project could depend on. It is not limited to APIs nor even project boundaries that are customer-visible. (See the sections that follow.) A good example Architecture Diagram is in http://sac.eng.sun.com/LSARC/1995/132/commit.materials/interface.ps Get help from your case owner in completing the Architecture Diagram. #endif 9.2 Interface Table: Include Imported and Exported Interface Tables showing all customer-visible interfaces and inter-project interfaces and significant internal interfaces (inter-subsystem and inter-invocation). Interfaces are not just function calls. Include user interfaces (graphical, browser based, character based), configuration files, XML DTD's, database schemas, network protocols, port numbers, etc. #ifdef ADVICE The following sections ask for more detail and help "brainstorm" additional interfaces. Divide your table into sections that will be helpful to the reviewers (e.g., client-side versus server-side). Subdivide your table or use another method to distinguish Imported and Exported interfaces and "what kind" of component or interface. For example: Protocols, Libraries, Daemons, Command Line Utilities (applications, configuration or administration tools), Graphical User Interfaces, Character User Interfaces, Command Line Interpreters, Input/Output File Formats, Configuration Files, Databases, Log files. If it is too much to describe all at once, it is probably too much to review all at once; discuss with your case owner subdividing the review, perhaps into separate projects of a common "program". Propose for *each* interface a stability/commitment classification -- Committed (formerly Public, Stable, or Standard), Uncommitted (formerly Unstable), Volatile, Project Private, etc. -- per the SAC Interface Taxonomy document in http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=interface_taxonomy.bp Importing a Project Private interface between projects or a Consolidation Private interface across consolidation boundaries requires an interface contract be submitted and reviewed (see the template in http://sac.eng.sun.com/arc/ARC-Templates/contract ). #endif EXPORTED INTERFACES: Proposed Specified Former Stability Interface Stability in what Classification Name Classification document? or Other Comments ------------------ ------------- -------------- -------------------- Your project will not be easily reviewed without information here ------------------ ------------- -------------- -------------------- IMPORTED INTERFACES: Proposed Specified in Former Stability, Interface New Stability what case no. Contract Number, Name Classification &/or document? or Other Comments ------------------ -------------- -------------- -------------------- Your project will not be easily reviewed without information here ------------------ ------------- -------------- -------------------- #ifdef ADVICE A good example Interface Table is in http://sac.eng.sun.com/LSARC/1995/132/commit.materials/interface.ps It uses letters to tie the table to the Architecture Diagram. A project can't be approved until the interfaces are enumerated and assigned stability classifications and -- where appropriate -- a specification of the syntax and semantics is submitted and reviewed. Get help from your case owner in completing the interface table. For a Committed interface, a reasonably-brief specification must be submitted with the case materials, and reviewed by the committee. Customer documentation is also required. For a standard interface, a pointer to the specification (with version number or date) is usually sufficient. Some standards lack bindings to a specific programming language; if you've chosen syntax, arguments, names, or numbers, make clear what you've added beyond the standard specification. Also document any differences between the specification and the implementation -- implementation-specific details, unimplemented features, extensions, requirements, assumptions. Uncommitted and Volatile interfaces also require a specification be submitted and reviewed. Customer documentation is also expected. It should for all stability classifications, but must for Uncommitted or Volatile interfaces, describe the risk that in a future release the interface may be changed or dropped; this is best done by using the terms defined in the Solaris attributes(5) man page. For a Committed Private interface, the ARC will at least assure that the interface can satisfy its purpose and support evolution so that "normal use" will be sufficiently seamless between invocations, between hosts, and across releases. For a contracted interface, the specification already agreed between the parties should be reviewed by the ARC. The ARC will at least assure that the interface can satisfy its purpose and support evolution in the way described in the contract. For an imported interface, the goal is to specify what aspects of the interface must not change, in order to avoid breaking your implementation. #endif 9.3 Identify names and contents of packages, directories, libraries, databases, etc. Identify package abbreviations (SUNWxxx) and contents figuratively ("configuration command line utilities"). #ifdef ADVICE The table may be integrated with the Interface Table or separate, but must be complete. If the project is to deliver any contents that have not been presented to the committee before approval, they must be added, perhaps as a fast track; talk to the case owner. SAC advice about packaging is in http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=packaging-1.bp and http://sac.eng.sun.com/PSARC/1993/271/materials SAC's filesystem layout guidelines for Solaris are in http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=install_locations.bp Here's a quick reference for installation locations: Type of File If Bundled If Unbundled ============================= =============== ============ user-invoked executables /usr/bin/ /opt/SUNWxxx/bin/ system administration utilities /usr/sbin/ /opt/SUNWxxx/sbin/ daemons, libraries /usr/lib/ /opt/SUNWxxx/lib/ configuration files /etc/ /etc/opt/SUNWxxx/ changing files (logs, databases) /var/ /var/opt/SUNWxxx/ SUNWxxx is normally the package abbreviation, but is sometimes an "umbrella" package name, so related packages are grouped. When this is done, version-number-specific subdirectories are advised, so that multiple versions can simultaneously find their compatible files. Any program invoked automatically when appropriate is effectively a daemon, and should live in /usr/lib. Also, no code names must appear in the final product. Subdirectories of these installation locations may be used when several files are being added. Installation location and packaging guidelines for Linux are in: http://sac.eng.sun.com/WSARC/2004/304/inception.materials/current http://sac.eng.sun.com/WSARC/2004/009/materials/current #endif 9.4 Package manifest: #ifdef ADVICE This may be provided in a separate file and referenced here. A package manifest should list the name and file type of every file in every package that is part of the project. Give each package abbreviation (SUNWxxx) and whether it is required, recommended, or optional. Identify dependencies between packages stated by the packages. At Commitment Review, a draft should be available. Before release, but typically long after ARC Commitment, the project team should submit to the ARC the final package manifest, generally from the pkgmap(4) files. An exceptionally nice Packaging list is in: http://sac.eng.sun.com/LSARC/1995/132/commit.materials/package.ps #endif 10. The operational environment: #ifdef ADVICE (Each of the following questions should be answered for every component of the project to which it applies. For example, a project with multiple Solaris applications would specify the exit status of them all. Manpages commonly present some of this information, but be sure the remaining questions are answered for those components.) #endif 10.1 Command line or calling syntax: What options/operands are supported? #ifndef WINDOWS 10.1S Do they conform to PSARC/1999/645 command syntax guidelines, an extension of the Single Unix Specifications rules? Are any of the "CLIP" extensions to the SUS guidelines used? #ifdef ADVICE In particular, note the length limit: from 2 to 9 characters. Guideline 14 suggests a command that takes subcommands (a la sccs) for grouping similar operations and avoiding long command names. #endif #endif 10.1.1 Is there support for standard forms, e.g. X11(5) manpage's "-display", etc.? If not, why not? 10.1.2 Are these options propagated to sub-environments? 10.2 Can it be included in a shell pipeline? How does it use standard input, output and error? 10.3 Environment Variables: 10.3.1 What environment variables are used? Describe values and semantics. 10.3.2 What is the default behavior if the environment variable is not set? #ifdef ADVICE In general, environment variables aren't good interfaces: they're inconvenient, not very dynamic, not entirely MT-safe, one big namespace. If necessary at all, make them optional (unneeded for the typical user). #endif 10.3.3 What environment variables are set? 10.4 For Solaris, Linux, or other Unix programs, what are their exit status values? What nonzero status values have what meanings? #ifdef WINDOWS 10.5W What inter-component Windows messages are sent or intercepted? #else 10.5S Signals issued? Signals caught? (See "man signal".) What are their semantics? #ifdef ADVICE For example, daemons normally reread their configuration files when they catch SIGHUP. Do your daemons do that? Why not? Programs normally clean up and exit when they receive SIGINT (typically from typing a Ctrl-C), but debuggers do not. #endif #endif 10.6 Device drivers directly used (e.g. /dev/audio)? #ifdef WINDOWS 10.7W SYSTEM.INI, WIN.INI or other resource/configuration files or databases? Describe any files used between invocations. #else 10.7S .rc/defaults files, Java properties, GNOME GConf keys or other resource/configuration files or databases? Describe any files used between invocations. #endif 10.8 Does it use any "hidden" files (filename begins with "."), system files, or temporary files? 10.9 Does it use any locking files? Does it use Solaris locking facilities? #ifdef ADVICE fcntl(2) has long been the POSIX compliant interface for locking; XPG4.2 adds lockf(3C) which is less complicated. If the project uses locking, also answer #17.4. #endif 10.10 Can it execute remotely? In a distributed fashion? Is the user aware that the tool is executing remotely? #ifdef WINDOWS 10.11W For each Windows component (EXE, DLL or VxD) identify the name of the component and module identifier (EXE/DLL) or VxD ID (VxD)? If a module provides a plug-compatible replacement for a standard system component, identify the component and its version. Indicate whether VxD IDs are officially registered. #else 10.11S Solaris/Linux/Unix Libraries If you have code, include output from both "dump -Lv" and "ldd"; but note that the ARC wants to know what the project will deliver, regardless of what developers currently have. 10.11.1 What dynamic (aka "shared") libraries does it use directly or indirectly, including via dlopen/dlsym(3x)? 10.11.2 With what -R options will executables be built? 10.11.3 Does it use any static libraries? 10.11.4 What libraries does your project export? #ifdef ADVICE If your project exports Solaris libraries: (most, but not all, of these apply to Linux & other Unixes as well) A. SAC prefers dynamic (aka "shared") libraries only, to reduce disk and memory footprint and to insulate applications from future implementation changes in the library (picked up automatically). B. The library must include a version number, so that any necessary future incompatible change can be recognized as such. C. Review the Solaris Linker and Libraries Guide and follow the Library and Shared Object Requirements Best Practice http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=Libraries.bp D. Use the -R flag when linking to unbundled libraries, rather than depending on users to set LD_LIBRARY_PATH. The $ORIGIN construct can allow a product's binaries to find its libraries even if the install root directory is changed. F. C header files should work with both Sun cc and gcc in both C89 & C99 modes and with C++. PSARC/1991/041/final.guidelines lists requirements on header files. For details and other advice not yet binding on non-ON projects, see http://jurassic.eng.sun.com/shared/ON/general_docs/cstyle.ms.ps G. Libraries containing public interfaces should be provided for all supported ABI's on the platform unless there is a compelling reason not to. For Solaris, this includes 32-bit SPARC, 64-bit SPARC, 32-bit x86, and 64-bit x64. H. Consider using "mcs -c" to merge identification comments. I. C++ implementation and interfaces are more problematic; see LSARC/1993/571 and PSARC/2002/348 J. If your library can't run in all locales, discuss that with the ARC. K. We advise all libraries shipped as part of Solaris to be made "large file aware" (meaning, able to use files > 2GB, per PSARC/1995/289). L. In library routines, pipes (and pretty much everything else) should generally be opened with the close-on-exec flag. #endif #endif /* WINDOWS */ 10.12 Does your project use or ship database or persistent storage software? If not, skip the rest of this section. 10.12.1 What software does it use? 10.12.2 Does it meet the SAC Policy on using standard databases? (see the Database Policy at http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=dbpolicy.bp ) If NO, please provide the reason: [ ] does not meet technical requirements (please specify) [ ] product already shipping with non-compliant technology [ ] customer requires we use a specific database [ ] other (please describe) 10.12.3 Is the database technology available for customer use? 10.12.4 Does the customer have to explicitly manage/administer the technology? 10.13 Does the project depend on particular versions of supporting software (especially Java virtual machines)? If so, do you deliver a copy? What happens if a conflicting or incompatible version is already or subsequently installed on the system? 11. System Administration Interfaces: #ifdef ADVICE NOTE: For an explanation of Sun's packaging technology and standard package construction approaches see the Solaris 10 Application Packaging Developers Guide at: http://docs.sun.com/app/docs/doc/817-0406 For the package partition rules see: http://solaris.eng.sun.com/benet/Packaging/SW_Pkg_Rqrmts,v4_0.pdf #endif 11.1 How will the project's deliverables be installed? 11.2 How will the project's deliverables be uninstalled? #ifdef ADVICE Solaris products normally install via pkgadd (either directly or under the control of an installer UI) and uninstall with pkgrm. Install scripts are not interactive and must not assume they are running in the target environment due to features such as Jumpstart and Live Upgrade. #endif 11.3 How will the project's deliverables be configured and reconfigured? 11.4 Does it need installation within any global system tables? Does your package edit existing files in a common directory (/etc/vfstab for example)? If so, how do you remove your edits when your package is removed? If your package is reinstalled over itself, does it recognize that the edits are already there or does it make all new entries? #ifdef WINDOWS What Microsoft Windows registry entries are created or modified? #endif #ifdef ADVICE If an entry needs to be added to /etc/system in support of the new solid state fanbelt, it's important that the line not be added over and over with every execution. Solaris package class action scripts must be carefully constructed to work with systems using zones, Live Upgrade, Jumpstart, diskless clients, and a variety of other install/upgrade schemes. #endif 11.5 Does your package use components of other unbundled packages? If so, how do you find those packages? #ifdef ADVICE More and more of our unbundled packages are relocatable so that admins can use their filesystem space more efficiently. If the package you need has been relocated, you need to use the pkg* interfaces to find it. This usually happens at install time but may also be used periodically in case a package you need gets moved. For instance: $ pkginfo -x SUNWjdk.* | nawk ' /SUNW/{printf(" %s", $1) } ' returns all instances of SUNWjdk on the current host. Pkgparam can then be used to find the VERSION and BASEDIR for each instance. #endif 11.6 Can your product be installed to an alternate filesystem (using "pkgadd -R") for use with diskless/auto clients or live upgrade? #ifdef ADVICE Don't think that just because you are shipping a server product that it will never be installed with pkgadd's "-R" option. That's how jumpstart installs software to the server and how live upgrade does low-downtime system upgrades! If there are various package scripts (preinstall, postremove, etc) that presume "/" to be the root of the target filesystem, your package cannot be installed to a client nor is it jumpstart compatible. The root of the target filesystem is guaranteed to be ${PKG_INSTALL_ROOT:-/} in package scripts, not "/". #endif 11.7 Can your product be installed anywhere on the target system and still function (is it relocatable)? (BASEDIR) #ifdef ADVICE The administrator may not have enough room in your default base directory. If your product must be there and only there then it is not relocatable and that is a problem. NOTE: The "-R" option to pkgadd does not relocate, it selects a client filesystem. Administrators will relocate this package by editing the "basedir=" entry in an admin file like /var/sadm/install/admin/default. #endif 11.7.1 Has your project changed or introduced any package procedural scripts (postinstall, preremove, etc)? If YES, are these scripts well-behaved with respect to alternate roots? That is, when these packages are added or removed using -R, do they cause any changes to be made to /? The correct answers are either "No" or "Yes, Yes, and No". #ifdef ADVICE This question is necessary to ensure that packages follow the rules necessary for Live Upgrade and for clients. #endif 11.8 Even relocatable packages may have one or two elements that *must* go in a certain place (/etc files for example). Are these "absolute" elements in the pkgmap or are they being installed with a postinstall script? If installed with a postinstall, how does the administrator check their integrity (how does pkgchk know about them)? #ifdef ADVICE If you deliver root and /usr files in the same package, your package *must* be installed on a host with root and /usr local (you must document this). On Solaris 2.6, such packages can be installed to a diskless or autoclient successfully only if the package is installed to the client from the server using "-R". If the package is a part of Solaris, Solaris rules apply - root goes into one package, /usr into another and /opt into another. See http://solaris.eng.sun.com/benet/Packaging/SW_Pkg_Rqrmts,v4_0.pdf for details #endif 11.9 How does a new version of your package upgrade a prior version? #ifdef ADVICE When a new version of your package is installed to replace an old version (an upgrade), the old version *must* be removed otherwise old patches will be able to clobber your new code. Some teams make the mistake of writing postremove scripts that delete required databases making upgrade nearly impossible. You want to make sure that you can inform the old package that it is being upgraded so that persistent data can be retained across the upgrade. For details, see the Application Packaging Developers Guide for Solaris: Advanced Package Generation Techniques, Upgrading Packages. This explanation is good except that a checkinstall script should be used to construct the upgrade script since the checkinstall is guaranteed to run at install time. NOTE: This upgrade will result in a package instance on the filesystem with a ".2" tagged onto the end. That's OK. The argument you pass to the packaging commands is a package instance not a package name. #endif 11.10 Does your package replace a filesystem object delivered by a prior package? If so, how do you inform the other package that it doesn't own this file anymore? How do you return the original package to its original state if your package is pkgrm'd? #ifdef ADVICE This is very tricky because a future patch to the original package can replace the original package's file (breaking your product). This should be avoided like a rabid dog! If you must do this, you must make a contract with the producers of the package you are modifying. They will have to provide two sets of patches, one with a hole where your file would be (patch A) and one with the old file (patch B). Patch A will obsolete patch B and your product will need to deliver patch A as a part of your product. If you actually replace the old file using patch A, your life is a little simpler - the old package now owns your new file and the other team delivers it. If you just use the patch as a placeholder to prohibit other patch B's, your package will need to do more work. It will need to store the old file in the $PKGSAV directory using a preinstall script and use removef to delete that file from the old package. In a postremove script, your package will restore the old file to its original location and use installf to register it with its original package again. #endif 11.11 Have you grouped generic functionalities that may be used by other projects into their own packages (KLG widgets, a third-party set of device drivers)? If not how do other projects know this generic functionality is installed? Are you using existing classes and libraries as far as possible? 11.12 How is it started? #ifdef WINDOWS For Microsoft Windows components which are automatically started, what mechanism is used to do so? For components which are started interactively, what program group entry is used? Does the component include any mechanism for implicit starting, e.g. by association with a file type? #else For a daemon: does it use SMF (if on Solaris) or inetd? If not, why not? If SMF, does it comply with the SMF best practices in http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=SMF.bp ? #ifdef ADVICE SMF is required for any service that may be installed on Solaris 10 or later, even if an rc script is also delivered for older releases. The committee will want to know your service FMRI, any configurable properties, and the roles which may configure it. #endif #endif 11.13 Does it use a naming service such as NIS, DNS, LDAP? Directly, or through the name service switch? 11.14 What are its on-going maintenance requirements (e.g. keeping global tables up to date, trimming files)? #ifdef ADVICE The committee advises low-volume logging to use the system logging daemon; see syslog(3). For high-volume logging, the committee wants on-going maintenance to be automated; projects might allow the user to select a maximum size that automatically gets truncated to the most recent or oldest entries; or the project may provide a script or procedure for performing the truncation. Consider the reliability of the truncation, so that entries cannot be lost if they are produced during the truncation. #endif 11.15 Can administration be done from a remote machine? How? #ifdef ADVICE When setting X's DISPLAY variable for a remote execution of an administration GUI is recommended, the committee advises that the GUI display in the window title the hostname (of the system being administered). #endif 11.16 Can all GUI administration also be performed without the GUI? How? #ifdef ADVICE The committee often advises that administration be performable via a character-only interface (Command line interpreter, or command-line utilities), as well, since system administrators sometimes have only a terminal or laptop computer available. Users who need accessibility helpers to interact with the computer often also benefit from character interfaces, making this in many cases a requirement to meet government regulations such as the U.S. Section 508 and similar rules in Europe. Curses is another option, but admins can't build shell scripts on it. #endif 11.17 What command or scripting language is used? 11.18 Does the project include runtime license checking? Why? How is it accomplished? How does it cope with changes of the underlying system due to hardware replacement or virtualization? 11.19 Are there any restrictions or other architectural effects from contractual obligations, copyright restrictions, technology royalty structure, or open source license requirements? 12. The Window System/Desktop Operational Environment: 12.0 Does the project include a GUI (Graphical User Interface)? If not, say "NONE" and remove all this section's subsections. 12.1 If the project includes a GUI (Graphical User Interface), case materials should summarize the GUI's "User Model" in a few pages; that is, the objects that the user sees or must know about, their logical state, and the operations the user may perform on them. #ifdef ADVICE User's Guides, which describe a lot of mechanics, are often too large. If you must point the committee to a large document, tell us what pages or sections include what information that we need. #endif 12.2 Do the GUI components share the Look and Feel of their product? In other words, does each component appear to be part of the same product family? 12.3 Have the GUI components had Human Computer Interaction (HCI) usability consultation? What recommendations were and were not heeded? #ifdef ADVICE The committee recommends that every GUI seek HCI consultation. HCI advice should be followed or discussed with the ARC. For management applications, the interface should be reviewed by the UIRB. #endif #ifndef WINDOWS /* The following is NOT for Windows, but Solaris */ 12.4S X resources/defaults: Are they supported? What is the application's "class" name? What resources does it depend on? Are the resources propagated to sub-environments? #ifdef ADVICE The location of the X resource files and resources documented for customers should be listed on the manpage. Resources named *only* in the X resource file are Private. #endif 12.5S X atoms: What X atoms--properties, selection targets, types--does it depend on? Which ones does it export, and what are their types? How does it respond to property change notification and ICCCM client messages? (E.g. Do you respond to "save workspace"?) Do the properties need to be visible across multiple labeled zones in a trusted desktop? #ifdef ADVICE Private X11 atom names should use a prefix registered with the X.Org Foundation, such as _SUN_, and a project-specific prefix. #endif 12.6S What window-system toolkit does your project depend on? 12.7S What specific desktop integration work is planned? (GNOME examples: Nautilus icons for new data types, .desktop files to make applications show up in the menus, panel "applets") 12.7S What X extensions does it use (e.g. GLX, SHM, DGA, RENDER, Multi-Buffering)? (Hint: use "xdpyinfo") 12.8S How many colormap entries does it use? How does it share them? Does it rely on CDE color allocation? Is your project tested with both 24 bit TrueColor and 8 bit PseudoColor default visuals? #ifdef ADVICE The committee advises projects to minimize the number of colors consumed, since there are still a lot of 8-bit frame buffers out there. #endif 12.9S Describe your project's support for User Interface facilities including Help, Undo, Cut/Paste, Drag and Drop, Props, Find, Stop? #ifdef ADVICE If projects do not support Help and Undo, explain why not. Cut/Paste: text widgets normally support it for you. If this works, but you have no non-text support for Cut/Paste, say "text-only". #endif 12.10S When your windows are stretched ("maximized"), do your widgets expand to use the extra screen real estate? Is that part of GUI testing? What happens when you maximize in Xinerama mode? #ifdef ADVICE Programmatic adaptation of window sizing and layout is also helpful when the GUI is localized. #endif 12.11S Will it work with remote and/or low-bandwidth displays, such as Sun Rays, VNC viewers, and remote X servers? 12.12S Desktop Environments: 12.12.1 Does the GUI run correctly under both the default CDE window manager (dtwm) and the default GNOME window manager (metacity?) On Linux systems, does it run with the default KDE window manager? #ifdef ADVICE Really everything should work with any ICCCM-compliant window manager, but these are the most important to verify. Java applications have often had troubles with different window managers. #endif 12.12.2 Are the GUIs compliant with the style guides for the look-and-feel employed? 12.13 Is the application usable with accessibility aids like screen readers and magnifiers? #ifdef ADVICE If you're not using gtk+ or Java -- for example, using Motif -- it will be a problem. See http://accessibility.eng.sun.com/ for more advice and contacts. #endif #else /* below is for Microsoft WINDOWS */ 12.4W Describe your project's support for User Interface facilities 12.5W Are drag 'n' drop and cut 'n' paste supported where meaningful? 12.6W Is each GUI compliant with the Windows Style Guide? 12.7W If your software implements any Windows or other PC API or protocol for use by Solaris-based components, what subset of that API or protocol is supported? Do the semantics diverge from those published for that API or protocol? 12.8W If your software provides access to Solaris resources or services to Windows-based clients by wrapping those services in a Windows or other PC API or protocol, what subset of that API or protocol is supported? 12.9W Is it compatible with Windows emulation (such as Wine) or virtualized Windows (such as under VMWare)? If not, what technical aspects preclude compatibility and what would it take to remove the incompatibility? 12.10W Does it run well in remote Windows display environments such as Windows RDP, Sun Secure Global Desktop (SGD, aka Tarantella), or Citrix? If not, what technical aspects cause problems and what would it take to resolve them? #endif /* WINDOWS */ 13. Brainstorming Interfaces (exported and imported): Include in your Interface Table any of the following that apply. You may comment on them here, if you wish. 13.1 Exported Library APIs and ABIs exposed to customers 13.1.1 The name of the library 13.1.2 The installation location for the library 13.1.3 The prefix(es) reserved for use by the library and its header files. 13.1.4 The syntax and semantics of every symbol exported by the library. #ifdef ADVICE Provide a manpage for each function, plus one for the whole library (which names the file(s) to #include and the linking instructions). #endif 13.1.5 Compile time symbols (#defines or #ifdefs) defined by the project? 13.1.6 Are there any library or headerfile symbols that don't start with one of those prefixes? #ifdef ADVICE The committee recommends testing for unexpected library symbols. #endif 13.2 Protocols (public or private, including RPCs) #ifdef ADVICE RPC protocols must be registered via E-mail to rpc@sun. Port numbers and other Internet numbers we register directly with the Internet Assigned Numbers Authority, http://www.iana.org/ . #endif 13.3 Drag and Drop: what objects and what are the semantics? 13.4 GNOME ORB (bonobo) remote calls, Web service calls (SOAP, etc.), ToolTalk messages? 13.5 Files used as an interface, e.g. Resources, config files, etc. 13.6 Significant file formats, names, syntax, and semantics? Is there an /etc/magic entry for any new file format? What will file(1) say? #ifdef ADVICE Support a comment syntax (preferably # to end-of-line) in each customer-editable configuration file. Configuration by a administrative command is preferable to hand-editing files. #endif 13.7 Interfaces to applications it interoperates or communicates with? (Perhaps pipes, shared memory.) 13.8 Is there a public namespace? (Can third parties create names in your namespace?) How is this administered? 13.9 Other External Interfaces? 13.10 Brainstorming Significant Internal Interfaces #ifdef ADVICE These interfaces are likely to be Private, but there are various flavors of Private, some of which need ARC review. #endif 13.11 Protocols (public or private) 13.12 Private ORB, RPC, SOAP, RMI, etc. transactions 13.13 Files and their Formats #ifdef ADVICE Private configuration files that save information behind a program or GUI, but which are not to be edited by hand, should (if a comment syntax is supported) have a comment saying not to edit it, which mentions what program(s) modify it. #endif 13.14 Do any internal interfaces save state across invocations? 13.15 Other Internal Interfaces? 14. Questions for Every Interface: These questions should be asked for every one of the project's interfaces; the answers are therefore often listed in Section 9.2 (Don't repeat.) Only the interesting answers are normally discussed. 14.1 Propose the stability/commitment classification of the interface -- Committed (formerly Public, Stable or Standard), Uncommitted (formerly Unstable), Volatile, Project Private, etc. -- per the SAC Interface Taxonomy document at http://sac.sfbay/cgi-bin/bp.cgi?NAME=interface_taxonomy.bp #ifdef ADVICE Some interfaces (e.g., RPC, a filename used) have one commitment level, but the actual messages transmitted (or file contents or format) may have a different stability classification. #endif 14.2 Who controls the interface (i.e., could make changes to it)? Point out any interfaces not solely controlled by Sun. 14.3 Interface Specification: 14.3.1 Where is the interface specified (documented)? 14.3.2 Is the specification complete enough for a re-implementation? 14.3.3 Will the project deliver to customers documentation for the interface? 14.3.4 Are the interfaces documented clearly enough for a non-Sun client to use them successfully? 14.4 Interface Versioning and Projected Evolution #ifdef ADVICE Committed interfaces cannot change incompatibly (correctly, cannot remove support for the previous version, even if a new version can coexist) until either: A. A major release of the product (which is not envisioned for Solaris), or B. the end-of-life process for features (aka EOF) as described in http://sac.eng.sun.com/BestPractices/ToDo/Obsolete_EOF/ is followed; this requires demonstrating that the interface is Obsolete -- i.e., generally unused -- often because a better alternative exists and has "universal" acceptance. Uncommitted interfaces are not normally changed incompatibly. Such a change would need thoughtful justification to the committee. Committed Private and Sun Private interfaces have much the same restriction, but incompatible change can often be allowed, if it is sufficiently hidden from the customer, or otherwise "managed" so that "normal use" is not affected by the interface's evolution. #endif 14.4.1 Present Change: if any interface is an update to or replacement for a previous one, what was the stability classification of the previous version? Is this backwards-compatible? Describe any migration story to mitigate the conversion. 14.4.2 Future Evolution: Even if an interface is new, it should be prepared for evolution. How will a transition to a new version to be accomplished? What are the expected consequences to ISVs and users and administrators? What provisions are made now to minimize or manage the pain (to clients) of future evolution? #ifdef WINDOWS 14.4.3 For Microsoft Windows components that install on top of an existing product (such as PC-X on top of PC-NFSpro): are there common files that should only be upgraded if the files being installed have a new version? #endif 15. Performance and Scalability: #ifdef ADVICE Our goal is to assure the architectural choices will likely lead to acceptable performance and avoid surprising resource consumption. #endif 15.1 What are the performance goals of the project? How were they evaluated (or how will they be)? On what type of test platform? How will performance regressions be identified? #ifdef ADVICE Significantly reduced performance can make an interface no longer suited to a task for which it was appropriate; that would be an architectural issue. In any case, the committee recommends that test plans include verifying that performance regression is identified, so it can be evaluated. If the performance of the typical case is improved, but certain usage performs drastically worse, a careful, educated tradeoff must be made. #endif 15.2 Are there any limits to scalability, such as a fixed-size array forcing a maximum number of clients, users, simultaneous connections, etc.? Are any data structures (e.g., kernel structures) so huge that large numbers of them are impractical? 15.3 Resource Consumption: #ifdef ADVICE Resources and constraints might be how many processors can be used, kernel memory, file descriptors, virtual memory, filesystem space, ports consumed. #endif 15.3.1 Attempt to describe resource consumption scaling, even crudely. For example, if each client consumes 1MB of memory, you could say: Memory_required = 1MB * Nclients 15.3.2 Which resources are likely to be bottlenecks? 15.4 Does the application pause for significant amounts of time? Can the user interact with the application while it is performing long-duration tasks? #ifdef ADVICE If so, consider using threads (or forking a subprocess) to allow user interaction in the interim. #endif 15.5 Multi-threading: What is your project's MT model? What must an MT client do to use your interface(s) safely? How does your project use threads internally? How does it expect its client to use threads? If it uses call-backs, can the called entity create a thread and recursively call back? Is it prepared for multi-thread & multi-core systems like Niagara and Opteron? #ifdef ADVICE Every API potentially will be used by MT clients. Describe what synchronization (locking) would need to be performed by such a client. Is this information documented for your customers? Most ARC opinions should state this information. For more information about threading terminology, see http://sac.eng.sun.com/BestPractices/ToDo/MTsafety/ #endif 15.6 What is the impact on system performance (positive or negative)? 15.6.1 What is the average memory usage or working set of this component? #ifdef WINDOWS 15.6.2W How much of this is locked down? 15.6.3W What system resources are consumed by each component under Windows? #else 15.6.2S How much of this is shared/sharable by other apps? #ifdef ADVICE The "pmap" command and the program performance analysis tools in Sun Studio can help you measure and improve memory usage for C/C++ programs. #endif #endif /* WINDOWS */ 15.7 Does this application "wake up" periodically? How often and under what conditions? What is the working set associated with this behavior? 15.8 Will it require large files/databases (for example, new fonts)? 15.9 Do files/databases or heap space tend to grow with time/load? What mechanisms does the user have to use to control this? What happens to performance/system load? 15.10 What are the project's effects on boot time requirements? 16. Security: Include a thorough description of the security assumptions, capabilities and any potential risks (possible attack points) being introduced by your project. A separate Security Questionnaire http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=Security.bp is provided for more detailed guidance on the necessary information. Cases are encouraged to fill out and include the Security questionnaire (leveraging references to existing documentation) in the case materials. 16.1 What security issues do you address in your project? 16.2 What security concerns might customers or reviewers have? 16.3 Are any components (e.g., encryption) subject to export restrictions? Why or why not? 16.4 How are particularly security-critical data like passwords treated? 17. Availability and Serviceability 17.1 How will it respond to failures? (Does it ever require reboot? Can it lock up? Is there a way for the user to "unstick it"?) 17.2 How does your project deal with network failures (including partition and re-integration)? 17.3 Can it save and restore state? Is any special action required if the filesystem is rolled-back to previous state (such as via ZFS or other filesystem snapshot technologies)? 17.4 Can it checkpoint and recover? Can its files be corrupted by failures? Does it clean up any locks/files after crashes? 17.5 Will it participate in the Solaris Fault Management Architecture (http://fma.eng.sun.com/)? 17.6 Can the project's deliverables be patched and upgraded without requiring a reboot? Without a noticeable service interruption? 17.7 How will patches be installed? 18. Adaptability to a Changing World: 18.1 Any plans for supporting operating systems other than Solaris (Linux, Microsoft Windows, MacOS X, AIX, HP/UX, etc.)? 18.2 How does it deal with issues in the 64-bit world, including 64-bit address spaces, 64-bit integers, and 64-bit files? 18.3 How will the project provide services to other projects? 18.3.1 Current or planned usage of CORBA IDL, IIOP, and an ORB? If an ORB, hich one (Bonobo, Java IDL, ...)? 18.3.2 Current or planned Java Beans, especially J2EE? 18.3.3 Current or planned Web Services interfaces (SOAP, etc.?) 18.4 What is its relationship (or difficulties) with . . . 18.4.1 the Internet? Web Services? 18.4.2 Java? J2EE? Application Servers? 18.4.3 "Network of Things" (thin clients, portable devices, cell phones, wireless networking, kitchen appliances with IP addresses?) 18.4.4 Multimedia? 18.4.5 Networked storage (SANs, NAS) 18.4.5 Infiniband? 18.4.6 Network identity services? 18.4.7 Virtualized environments (Xen, Zones, VMWare)? 19. Issues? Please identify the issues for which you would like ARC guidance. (e.g. Interface classification, deviations from standards, architectural conflicts, release constraints...) Any issues outstanding from previous reviews (or the case's mail archive)? 20. Appendices and References #ifdef ADVICE Files must be in one of the acceptable file formats: ASCII text PDF HTML PostScript Discuss any other form with your case owner and/or the SAC coordinator via E-mail to lsarc-materials@sac. In particular, framemaker, staroffice, powerpoint... formats are almost never acceptable. #endif 20.1 Interface Tables, Package Manifests, etc 20.2 References to other documents (one-pager, design papers, interface contracts, etc.). Copies are to be placed in the case directory. 20.3 Comments For Us? 20.3.1 How many engineer hours went into preparation of case materials, including answering this questionnaire (that would not otherwise have been needed for other purposes)? 20.3.2 Do you think it was time well spent? 20.3.3 How many engineer hours went into answering this questionnaire alone? 20.3.4 Comments on this questionnaire should be mailed to lsarc-chair@sac.eng.sun.com. 20.3.5 Comments on your case owner, the review process, or the experience may be placed here if they're not too personal, may be mailed to the chair or arc-chairs@sac, or may be expressed to John Plocher (x87604), or your divisional CTO. #ifdef ADVICE A. Other Considerations for Projects Please see the following documents which attempt to enumerate additional items which your project is responsible for understanding and addressing: SAC Best Practices: http://sac.eng.sun.com/BestPractices SAC Other Considerations: http://sac.eng.sun.com/arc/ReviewQuestions/OtherConsiderations #endif