@(#) LSARC Questions Version 2.0t @(#)LSARC 1.29 05/10/02 __________________________________________________________________ #ifdef REMOVE #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/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, 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 /shared/sac/doc/Client.Handbook/ The distinction between Inception and Commitment reviews is on pages 7 and 8. /shared/sac should work in the Engineering domain. In other domains, substitute /net/sac.eng/export/sac or use SunWeb's http://sac.eng/sac 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? LSARC 2007/431 0.2 This questionnaire is for an [X] Inception Review or [ ] Commitment Review 0.3 Name(s) of person(s) answering the questions? Mayuresh Nirhali 1. What specifically is the proposal that we are reviewing? Integrating DBI PostgreSQL Interface for Perl in Solaris 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. PostgreSQL version 8.1 was integrated into Nevada & S10u2 in Spring 2006. The core product does not include any interface with Perl. The DBD::Pg driver, that is the PostgreSQL DBI interface will allow perl programs to work with PostgreSQL database. This project aims at integrating the DBD::Pg driver into Solaris. #ifdef ADVICE An example Summary may be found in the /shared/sac/PSARC/1995/224/opinion.* #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", or "micro" change and why? (See the document in /shared/sac/doc/release.taxonomy.) This is a new product. 2. What is the motivation for it? What are the expected benefits for Sun? By what criteria will you judge its success? Inclusion of DBD::Pg and DBI perl modules would strengthen Solaris as Out-of-the-Box platform for Perl-Postgres application developers. Considering the amount of perl developers use Postgres on Solaris, this will increase the Postgres offering on Solaris significantly. 3. The plan: 3.1 Who (what groups in what business units) are working on it? Solaris Revenue Product Engineering (engineering resources) and the Database Technology Group (strategy). 3.2 What is the current status? We are ready to integrate Perl DBI 1.58 and DBD::Pg 1.49 into Solaris. 3.3 Has a design review been done? PgAdmin III is open source, and have their own review process. We suspect much of the code has gone through fairly thorough review -- it is a mature open source community. #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? DB PAC #ifdef ADVICE PACs are registered with the Sun PLCPtool http://sunplcptool.central.sun.com/ #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)? None. 4.2 What non-Sun projects does this project depend upon? None. 4.3 What other projects depend on this one? None. 4.4 What other active projects at Sun are related to your project, and how are they related? None 4.5 What future projects should be started or avoided to help your project succeed, and why? None. 5. What technical approach has been selected by the project? We currently support postgreSQL, a fully-fledged enterprise database. However, postgres currently cannot be used as backend for perl applications. The generic db interface (DBI) and postgres specific driver (DBD::Pg) bridge this gap and strenghten postgres offering on Solaris. #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? Bundled What are your delivery vehicles (WOS, CTEAM...) WOS Identify package abbreviations, directory names, library names, databases, etc. Please see package map (pkgmap.txt, in case materials) #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. None. 7.2 Are Solaris components expected to work on SPARC and Intel? If not, why? What will be affected in porting? Any problems if porting to another architecture were desirable? None. Already ported to Solaris by the perl community. The case is just for integration. 7.3 Are there issues with "binary" interfaces, which would be incompatible on various instruction set architectures? No #ifdef WINDOWS 7.4W For Microsoft Windows components, what is the minimal hardware configuration supported (e.g., Intel 386 with 8mb of memory)? #endif 8. Compatibility and Interoperability (Consider a compatibility matrix, if the information is nontrivial.) 8.1 OS compatibility: 8.1.1 For Solaris components, what Solaris release(s) does it run on or work with? Solaris 10 8.1.2 Does it run on Linux? What distribution(s)n and version(s)? No. We are not shipping the Linux version. 8.1.3 Might the project need any extra adaptation to work successfully with future (i.e., later) releases? patches? None. #ifdef WINDOWS 8.1.3 For Microsoft Windows components, does it run on Windows 3.x? Windows 95/98/ME? NT/W2K/XP? 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.2S Do Solaris components depend on kernel features not in the default kernel (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? No 8.3 Do Solaris components use any system interfaces, commands, or features not in X/Open CAE SUSv2 and XNS5? No #ifdef ADVICE Read "man standards" for what those abbreviations mean. Projects using system (or other project) interfaces that are neither Standard nor Stable (formerly Public) should explain to the ARC why the risk of being broken by an incompatible change are sufficiently low, and how the risk will be managed. Before release, but typically long after ARC Commitment, the project team should submit to the ARC for review the "ABI application certification" results for all executables and libraries that run on Solaris. See http://www.sun.com/developers/tools/appcer/t . #endif 8.4 Do Linux components use any interfaces, commands, or features not in the Linux System Base 1.3? N/A #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.) LSARC/2006/655 - PostgreSQL 8.2 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? None #ifdef ADVICE See the Internationalization Best Practice document. http://sac.eng/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/Intel ABI, OMG/CORBA, POSIX, SVID, XPG (X/Open Portability Guide), RFCs, national or international standards. Include version numbers. None 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? Both DBD::Pg and DBI are perl modules. Different versions of both these products can co-exist on the machine. By default they will be linked to /usr/bin/perl. They can also be linked to other perl versions by including them in the perl INC path. Similarly, /usr/bin/perl can include alternate DBD::Pg and DBI path. 8.8 Does the project move, disable, delete, circumvent or change any files, components, or services outside the project? No 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? No #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? None 8.11 Can customization (e.g., OEM relabeling) be accomplished via resource files that are separable from the source code? No. No customization possible. 8.12 Device Drivers: 8.12.1 Does this project deliver any device drivers? No 8.12.2 Does it conform to the Solaris DDI/DKI (manual sections 9e, 9f, & 9s)? N/A 8.12.3 Does it pass "DDICT" DDI compliance tool (available on Solaris DDK)? N/A 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. |<- Scope of DBI ->| .-. .--------------. .-------------. .-------. | |---| XYZ Driver |---| XYZ Engine | | Perl | | | `--------------' `-------------' | script| |A| |D| .--------------. .-------------. | using |--|P|--|B|---|Oracle Driver |---|Oracle Engine| | DBI | |I| |I| `--------------' `-------------' | API | | |... |methods| | |... Other drivers `-------' | |... `-' From the above diagram, We already have perl scripting language and Postgres engine available in Solaris. With this case, we would include the DBI and Postgres specific driver (DBD::Pg driver) to provide connectivity between perl and postgres backend. #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 /shared/sac/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 schemas, network protocols, port numbers, etc. See interfaces.txt, included with case materials #ifdef ADVICE Interfaces are not just function calls. Include user interfaces (graphical, browser based, character based), configuration files, XML schemas, network protocols, port numbers, etc. 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 -- "Standard", "Stable" (formerly Public), "Evolving", "Unstable" (intentionally Uncommitted), Contract Private, etc. -- per the SAC Interface Taxonomy document in http://sac.eng/cgi-bin/bp.cgi?NAME=interface_taxonomy.bp A "Contract Private" interface (between projects) requires a contract (see the template in /shared/sac/arc/ARC-Templates/contract) be submitted and reviewed. #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 /shared/sac/arc/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 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, they're not Standard (but are probably Public or Evolving). Also document any differences between the specification and the implementation -- implementation-specific details, unimplemented features, extensions, requirements, assumptions. For a Stable interface, a reasonably-brief specification must be submitted with the case materials, and reviewed by the committee. Customer documentation is also required. "Evolving", "Unstable", and "External" interfaces also require a specification be submitted and reviewed. Customer documentation is also expected. It should for all stability classifications, but must for Evolving or Unstable 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"). 2 packages will be added. 1. SUNWpmdbi 2. SUNWpmdbdpg #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 /shared/sac/doc/packaging.rules and /shared/sac/PSARC/1993/271/materials SAC's filesystem layout guidelines (such as they are) are in /shared/sac/doc/directory.layout/dirlayout.txt 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. #endif 9.4 Package manifest: See pkginfo.txt, pkgmap.txt in the case material #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: /shared/sac/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? N/A. #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(7) manpage's "-display", etc.? If not, why not? N/A 10.1.2 Are these options propagated to sub-environments? N/A 10.2 Can it be included in a shell pipeline? How does it use standard input, output and error? N/A. Such behavior is inherited from perl. 10.3 Environment Variables: N/A 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 programs, what are their exit status values? What nonzero status values have what meanings? N/A. Inherited from Perl. #ifdef WINDOWS 10.5W What inter-component Windows messages are sent or intercepted? #else 10.5S Signals issued? Signals caught? (See "man(5) 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)? N/A #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? N/A Describe any files used between invocations. N/A #endif 10.8 Does it use any "hidden" files (filename begins with "."), system files, or temporary files? No 10.9 Does it use any locking files? Does it use Solaris locking facilities? No #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? N/A. Such behavior is inherited from perl. #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 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. N/A. There are perl modules. 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: 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/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 all cc's -X 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/shared/ON/general_docs/cstyle.ms.ps G. Unless you're shipping the .o files, use "strip -x" to remove symbol table info that is useless without the .o files. 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. No 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/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? 11. System Administration Interfaces: Please see section 3 of the functional spec for more information about how DBD::Pg will be installed and configured. #ifdef ADVICE NOTE: For an explanation of Sun's packaging technology and standard package construction approaches see the Solaris 2.6 Application Packaging Developers Guide at: http://docs.sun.com:80/ab2/coll.45.4/PACKINSTALL/@Ab2TocView? For the package partition rules see: /net/benet.Eng/benet/Packaging/SW_Pkg_Rqrmts,v4.0.ps #endif 11.1 How will the project's deliverables be installed? pkgadd 11.2 How will the project's deliverables be uninstalled? pkgrm #ifdef ADVICE Solaris products normally install via pkgadd (either directly or using swmtool) and uninstall with pkgrm. Install scripts are not interactive. #endif 11.3 How will the project's deliverables be configured and reconfigured? N/A. No configuration required. 11.4 Does it need installation within any global system tables? No 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? N/A #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. The awk class action script that would demonstrate this idempotency would look like this: # /etc/system !install BEGIN { Line = "forceload: drv/fanbelt"; Inserted="false" } /^forceload: drv\/fanbelt/ { Inserted="true" } { print; } END { if (Inserted=="false") { print "forceload: drv/fanbelt" } } !remove /^forceload: drv\/fanbelt/ { next; } { print; } If the awk class were not being used, the conventional class action script to do the job would look like this: # i.forceld # Ignore stdin since there's only one file in this class anyway and # we know what it is. nawk ' BEGIN { Line = "forceload: drv/fanbelt"; Inserted="false" } /^forceload: drv\/fanbelt/ { Inserted="true" } { print; } END { if (Inserted=="false") { print "forceload: drv/fanbelt" } } ' < ${PKG_INSTALL_ROOT}/etc/system > ${PKG_INSTALL_ROOT}/etc/system.new mv ${PKG_INSTALL_ROOT}/etc/system.new ${PKG_INSTALL_ROOT}/etc/system And the removal script would look like this. #r.forceld # Ignore stdin since there's only one file in this class anyway and # we know what it is. awk ' /^forceload: drv\/fanbelt/ { next; } { print; } ' < ${PKG_INSTALL_ROOT}/etc/system > ${PKG_INSTALL_ROOT}/etc/system.new mv ${PKG_INSTALL_ROOT}/etc/system.new ${PKG_INSTALL_ROOT}/etc/system Note that these scripts always check to see if the job has already been done. If it has, they make no modifications. #endif 11.5 Does your package use components of other unbundled packages? If so, how do you find those packages? No #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? Yes. #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) Yes #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)? No. 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)? Both DBD::Pg and DBI packages will be installed within perl install directories. #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 /net/benet.Eng/benet/Packaging/SW_Pkg_Rqrmts,v4.0.ps for details #endif 11.9 How does a new version of your package upgrade a prior version? The new packages can replace the older ones. #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 Solarism 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? No #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? Yes. SUNWpmdbi is a generic interface for all database system specific drivers such as MySQL, DB2 etc. 11.12 How is it started? For a daemon: does it use inetd? If not, why not? N/A. It is perl module and will be invoked by perl internally. #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? #endif 11.13 Does it use a naming service such as NIS, DNS, LDAP? Directly, or through the name service switch? No 11.14 What are its on-going maintenance requirements (e.g. keeping global tables up to date, trimming files)? None #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? N/A #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? N/A #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. Curses is another option, but admins can't build shell scripts on it. #endif 11.17 What command or scripting language is used? perl 11.18 Does the project include runtime license checking? How is it accomplished? No 11.19 Are there any restrictions or other architectural effects from contractual obligations, copyright restrictions, or technology royalty structure? Since this is based on open source technology, not all changes can be controlled. The architecture *may* change in unexpected ways. Both DBD::Pg and DBI will manage this by providing a stable release of a regularly changing product. 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. NONE 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) None #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? None 13.4 GNOME ORB (bonobo) remote calls, Web service calls (SOAP, etc.), ToolTalk messages? None 13.5 Files used as an interface, e.g. Resources, config files, etc.) None 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? N/A #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.) None 13.8 Is there a public namespace? (Can third parties create names in your namespace?) How is this administered? N/A 13.9 Other External Interfaces? None 13.10 Brainstorming Significant Internal Interfaces None #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) None 13.12 Private ORB, RPC, SOAP, RMI, etc. transactions None 13.13 Files None #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? No 13.15 Other Internal Interfaces? None 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 -- "Standard", "Stable" (formerly Public), "Evolving", "Unstable" (intentionally Uncommitted), Contract Private, etc. -- per the SAC Interface Taxonomy document in /shared/sac/doc/interface.taxonomy See InterfaceTable.txt in case materials. #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. Both DBD::Pg and DBI are managed by the perl community. Interfaces may change in future and a new version would be released. Solaris should upgrade to new version in such a case. 14.3 Interface Specification: 14.3.1 Where is the interface specified (documented)? Both DBD::Pg driver and DBI have man entries. 14.3.2 Is the specification complete enough for a re-implementation? Yes 14.3.3 Will the project deliver to customers documentation for the interface? Yes 14.3.4 Are the interfaces documented clearly enough for a non-Sun client to use them successfully? Yes. Being open source project, all the documents are generally available 14.4 Interface Versioning and Projected Evolution #ifdef ADVICE Standard and Stable 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. "Evolving" 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. N/A 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? N/A #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? N/A #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? N/A 15.3 Resource Consumption: N/A. The behavior is inherited from Perl. #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? N/A #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? N/A. Both DBD::Pg and DBI are perl modules. #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)? No Impact. 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 3.x? Under Windows 95? #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 ONE 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? N/A 15.8 Will it require large files/databases (for example, new fonts)? No 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? N/A. Such behavior is inherited from Perl. 15.10 What are the project's effects on boot time requirements? None 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/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. Both DBD:;Pg and DBI are perl modules. Security features of Perl will be applicable here. Neither DBD::Pg nor DBI expose pose any security concerns of their own. 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? The behavior is inherited from Perl. #ifdef WINDOWS Can it lock up?) #else Can it lock up? Is there a way for the user to "unstick it"?) #endif 17.2 How does your project deal with network failures (including partition and re-integration)? The behavior is inherited from Perl. 17.3 Can it save and restore state? N/A 17.4 Can it checkpoint and recover? Can its files be corrupted by failures? Does it clean up any locks/files after crashes? N/A 17.5 Will it participate in the Solaris Fault Management Architecture (http://fma.eng/) No 17.6 Can the project's deliverables be patched and upgraded without requiring a reboot? Without a noticeable service interruption? Yes 17.7 How will patches be installed? patch tools 18. Adaptability to a Changing World: 18.1 Any plans for supporting operating systems other than Solaris (Linux, perhaps HP/UX, Microsoft Windows, AIX, etc.)? Both DBD:;Pg and DBI are perl modules and they are available on all the platform that is supported by perl. 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? The behavior is inherited from Perl. 18.3 How will the project provide services to other projects? The project will enable the perl apps to use Postgres as backend. 18.3.1 Current or planned usage of CORBA IDL, IIOP, and an ORB? If an ORB, hich one (Bonobo, Java IDL, ...)? N/A 18.3.2 Current or planned Java Beans, especially J2EE? N/A 18.3.3 Current or planned Web Services interfaces (SOAP, etc.?) N/A 18.4 What is its relationship (or difficulties) with . . . N/A. Both DBD::Pg and DBI are perl modules. 18.4.1 the Internet? Web Services? 18.4.2 Java? J2EE? Application Servers? 18.4.3 "Network of Things" (thin clients, portable devices, 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? 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 interfaces.txt pkgmap.txt 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)? 24 Hours, 1 person 20.3.2 Do you think it was time well spent? Yes 20.3.3 How many engineer hours went into answering this questionnaire alone? 5 Hours 20.3.4 Comments on this questionnaire should be mailed to lsarc-chair@sac.eng. 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), Cheryl Bisque (x51457) or Rob Gingell (x85555). #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/BestPractices SAC Other Considerations: http://sac.eng/arc/ReviewQuestions/OtherConsiderations #endif