From sacadmin Thu Jul 21 12:41:09 2005 Received: from phorcys.East.Sun.COM (phorcys.East.Sun.COM [129.148.174.143]) by sac.sfbay.sun.com (8.12.9+Sun/8.12.9) with ESMTP id j6LJf8Eu014759 for ; Thu, 21 Jul 2005 12:41:08 -0700 (PDT) Received: from phorcys.East.Sun.COM (localhost [127.0.0.1]) by phorcys.East.Sun.COM (8.13.4+Sun/8.13.4) with ESMTP id j6LJf8UY003765 for ; Thu, 21 Jul 2005 15:41:08 -0400 (EDT) Received: (from carlsonj@localhost) by phorcys.East.Sun.COM (8.13.4+Sun/8.13.4/Submit) id j6LJf8G5003762; Thu, 21 Jul 2005 15:41:08 -0400 (EDT) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <17119.64084.312401.532091@gargle.gargle.HOWL> Date: Thu, 21 Jul 2005 15:41:08 -0400 From: James Carlson To: psarc@sac.sfbay.sun.com Subject: 2005/430 Library Practice Clarification X-Mailer: VM 7.01 under Emacs 21.3.1 Status: RO Content-Length: 4111 I'm sponsoring this fast-track request for myself. The timer is set to 07/28/2005. This is an update to an existing best practice document. It has no release binding nor stability level. The current version 1.6 "Library and Shared Object Requirements" best practice document specifies the following policy: All shared objects intended for use on Solaris, whether or not they are delivered as a part of Solaris, or unbundled, must follow the rules enumerated below. In addition, it is strongly advised that the shared objects be free of any of the warnings. Under "Warnings" it includes: W3 A shared object containing only private interfaces should not deliver an associated compilation environment name. The "should not" message above has, over time, effectively been codified as "must not," due to the treatment of warnings, forcing excessive burden onto projects despite the "notes" included with the existing text. In particular, many projects deliver code into both a production gate (such as ON) as well as a testing gate (such as STC). In order to perform low-level project-related tests, the testing deliverables often make extensive use of private interfaces from within the production portion of the project, or otherwise rely on undocumented behaviors of the production portion. This undocumented dependency is generally regarded as safe because anyone making non-trivial changes to the production part would naturally be expected at least to use the provided tests to check for introduced problems, and because the contents of the test gate are not a shipped product. Such dependencies are rarely (if ever) reviewed by the ARC. In order to comply with W3 above for private libraries, projects in this situation would need to do one of the following: - Create a separate non-WOS-delivered package (containing the symlink, headers, and lint libraries) that must be installed on test machines in order to compile and use the tests. This creates a package that must be separately upgraded when the test system is upgraded, but keeps the "prohibited" parts out of the WOS. Unfortunately, the current intf_check tools do not distinguish between delivered and undelivered package contents. - Reclassify the private libraries as some form of Public interface, write man pages, and deliver them normally. This may involve a rewrite of the interface as well, as part of the reason it's private may well be that it's not fully baked. For some interfaces, it might not even be possible. - Write up an ARC case that records this intra-project dependency (same project effectively both exports and imports) in the test consolidation, includes a contract, and seeks a specific ARC exemption from the rule. Noting that detailed test plans including which private interfaces might be needed to accomplish specific tests are rarely available by project commitment time, it's worthwhile to note that this means every project gets one free "buddy" fast-track. All of the above options seem like much more work than is necessary here. Thus, instead, we propose adding the following to W3 in the best practice document: "Note: one instance in which a shared object containing only private interfaces may deliver an associated compilation environment name (and related materials, such as lint libraries and header files) is when the interfaces are to be used by a non-product (likely testing-related) delivery as part of the same project. The existence of such cases is the reason why this rule is just a warning. Databases that need to reference this exception case may refer to 'PSARC 2005/430' without requiring additional ARC review." References: "Library and Shared Object Requirements" http://sac.sfbay/cgi-bin/bp.cgi?NAME=Libraries.bp -- James Carlson, KISS Network Sun Microsystems / 1 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 From sacadmin Thu Jul 21 12:47:21 2005 Received: from jurassic.eng.sun.com (jurassic [129.146.108.38] (may be forged)) by sac.sfbay.sun.com (8.12.9+Sun/8.12.9) with ESMTP id j6LJlLEu014870 for ; Thu, 21 Jul 2005 12:47:21 -0700 (PDT) Received: from opus (vpn-129-150-24-158.SFBay.Sun.COM [129.150.24.158]) by jurassic.eng.sun.com (8.13.4+Sun/8.13.4) with SMTP id j6LJlErR921176; Thu, 21 Jul 2005 12:47:20 -0700 (PDT) Message-Id: <200507211947.j6LJlErR921176@jurassic.eng.sun.com> Date: Thu, 21 Jul 2005 09:38:27 -1000 (HST) From: "Joseph E. Kowalski III" Reply-To: "Joseph E. Kowalski III" Subject: Re: 2005/430 Library Practice Clarification To: psarc@sac.sfbay.sun.com, james.d.carlson@sun.com MIME-Version: 1.0 Content-Type: TEXT/plain; charset=us-ascii Content-MD5: eMFoRB63L5wzaep37p75zQ== X-Mailer: dtmail 1.3.0 @(#)CDE Version 1.6_73 SunOS 5.10 sun4u sparc Status: RO Content-Length: 4786 Since we are enhancing a best practice, how about a note such as: Human readable files (esp. include files) which contain only Private interfaces should contain a comment to that effect. I believe this is already common practice. - jek3 > Date: Thu, 21 Jul 2005 15:41:08 -0400 > From: James Carlson > Subject: 2005/430 Library Practice Clarification > To: psarc@sac.sfbay.sun.com > MIME-version: 1.0 > Content-transfer-encoding: 7BIT > X-PMX-Version: 5.0.1.144180 > > I'm sponsoring this fast-track request for myself. The timer is set > to 07/28/2005. > > This is an update to an existing best practice document. It has no > release binding nor stability level. > > The current version 1.6 "Library and Shared Object Requirements" best > practice document specifies the following policy: > > All shared objects intended for use on Solaris, > whether or not they are delivered as a part of Solaris, or > unbundled, must follow the rules enumerated below. In > addition, it is strongly advised that the shared objects be > free of any of the warnings. > > Under "Warnings" it includes: > > W3 A shared object containing only private interfaces should > not deliver an associated compilation environment name. > > The "should not" message above has, over time, effectively been > codified as "must not," due to the treatment of warnings, forcing > excessive burden onto projects despite the "notes" included with the > existing text. > > In particular, many projects deliver code into both a production gate > (such as ON) as well as a testing gate (such as STC). In order to > perform low-level project-related tests, the testing deliverables > often make extensive use of private interfaces from within the > production portion of the project, or otherwise rely on undocumented > behaviors of the production portion. This undocumented dependency is > generally regarded as safe because anyone making non-trivial changes > to the production part would naturally be expected at least to use the > provided tests to check for introduced problems, and because the > contents of the test gate are not a shipped product. Such > dependencies are rarely (if ever) reviewed by the ARC. > > In order to comply with W3 above for private libraries, projects in > this situation would need to do one of the following: > > - Create a separate non-WOS-delivered package (containing the > symlink, headers, and lint libraries) that must be installed on > test machines in order to compile and use the tests. This creates > a package that must be separately upgraded when the test system is > upgraded, but keeps the "prohibited" parts out of the WOS. > Unfortunately, the current intf_check tools do not distinguish > between delivered and undelivered package contents. > > - Reclassify the private libraries as some form of Public interface, > write man pages, and deliver them normally. This may involve a > rewrite of the interface as well, as part of the reason it's > private may well be that it's not fully baked. For some > interfaces, it might not even be possible. > > - Write up an ARC case that records this intra-project dependency > (same project effectively both exports and imports) in the test > consolidation, includes a contract, and seeks a specific ARC > exemption from the rule. Noting that detailed test plans > including which private interfaces might be needed to accomplish > specific tests are rarely available by project commitment time, > it's worthwhile to note that this means every project gets one > free "buddy" fast-track. > > All of the above options seem like much more work than is necessary > here. Thus, instead, we propose adding the following to W3 in the > best practice document: > > "Note: one instance in which a shared object containing only > private interfaces may deliver an associated compilation > environment name (and related materials, such as lint libraries > and header files) is when the interfaces are to be used by a > non-product (likely testing-related) delivery as part of the same > project. The existence of such cases is the reason why this rule > is just a warning. Databases that need to reference this > exception case may refer to 'PSARC 2005/430' without requiring > additional ARC review." > > References: > > "Library and Shared Object Requirements" > > http://sac.sfbay/cgi-bin/bp.cgi?NAME=Libraries.bp > > -- > James Carlson, KISS Network > Sun Microsystems / 1 Network Drive 71.232W Vox +1 781 442 2084 > MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 From sacadmin Thu Jul 21 12:56:41 2005 Received: from eastmail2bur.East.Sun.COM (eastmail2bur.East.Sun.COM [129.148.13.40]) by sac.sfbay.sun.com (8.12.9+Sun/8.12.9) with ESMTP id j6LJueEu016582 for ; Thu, 21 Jul 2005 12:56:40 -0700 (PDT) Received: from thunk.east.sun.com (thunk.East.Sun.COM [129.148.174.66]) by eastmail2bur.East.Sun.COM (8.12.10+Sun/8.12.10/ENSMAIL,v2.2) with ESMTP id j6LJudC0003797; Thu, 21 Jul 2005 15:56:39 -0400 (EDT) Received: from 127.0.0.1 (localhost [127.0.0.1]) by thunk.east.sun.com (8.13.4+Sun/8.13.4) with ESMTP id j6LJudhx023232; Thu, 21 Jul 2005 15:56:39 -0400 (EDT) Subject: Re: 2005/430 Library Practice Clarification From: Bill Sommerfeld To: James Carlson Cc: psarc@sac.sfbay.sun.com In-Reply-To: <17119.64084.312401.532091@gargle.gargle.HOWL> References: <17119.64084.312401.532091@gargle.gargle.HOWL> Content-Type: text/plain Message-Id: <1121975798.22298.236.camel@thunk> Mime-Version: 1.0 X-Mailer: Ximian Evolution 1.4.6.316 Date: Thu, 21 Jul 2005 15:56:39 -0400 Content-Transfer-Encoding: 7bit Status: RO Content-Length: 1085 On Thu, 2005-07-21 at 15:41, James Carlson wrote: > All of the above options seem like much more work than is necessary > here. Thus, instead, we propose adding the following to W3 in the > best practice document: > > "Note: one instance in which a shared object containing only > private interfaces may deliver an associated compilation > environment name (and related materials, such as lint libraries > and header files) is when the interfaces are to be used by a > non-product (likely testing-related) delivery as part of the same > project. The existence of such cases is the reason why this rule > is just a warning. Databases that need to reference this > exception case may refer to 'PSARC 2005/430' without requiring > additional ARC review." I'd like to suggest the following addition: "In order to discourage other use of these interfaces, header files should indicate in comments that the interfaces may be changed incompatibly or removed entirely without advance warning in future releases or patches." - Bill From sacadmin Thu Jul 21 13:01:02 2005 Received: from phorcys.East.Sun.COM (phorcys.East.Sun.COM [129.148.174.143]) by sac.sfbay.sun.com (8.12.9+Sun/8.12.9) with ESMTP id j6LK12Eu016933 for ; Thu, 21 Jul 2005 13:01:02 -0700 (PDT) Received: from phorcys.East.Sun.COM (localhost [127.0.0.1]) by phorcys.East.Sun.COM (8.13.4+Sun/8.13.4) with ESMTP id j6LK10nL003870; Thu, 21 Jul 2005 16:01:00 -0400 (EDT) Received: (from carlsonj@localhost) by phorcys.East.Sun.COM (8.13.4+Sun/8.13.4/Submit) id j6LK10mR003867; Thu, 21 Jul 2005 16:01:00 -0400 (EDT) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <17119.65276.830851.649543@gargle.gargle.HOWL> Date: Thu, 21 Jul 2005 16:01:00 -0400 From: James Carlson To: "Joseph E. Kowalski III" Cc: psarc@sac.sfbay.sun.com Subject: Re: 2005/430 Library Practice Clarification In-Reply-To: Joseph E. Kowalski III's message of 21 July 2005 09:38:27 References: <200507211947.j6LJlErR921176@jurassic.eng.sun.com> X-Mailer: VM 7.01 under Emacs 21.3.1 Status: RO Content-Length: 692 Joseph E. Kowalski III writes: > > Since we are enhancing a best practice, how about a note such as: > > Human readable files (esp. include files) which contain only > Private interfaces should contain a comment to that effect. > > I believe this is already common practice. Sounds reasonable to me. It might also be worth noting that obscuring the symbols or omitting the 'lib' prefix in an attempt to make linking "difficult" is not necessary or recommended. -- James Carlson, KISS Network Sun Microsystems / 1 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 From sacadmin Mon Aug 1 08:10:21 2005 Received: from phorcys.East.Sun.COM (phorcys.East.Sun.COM [129.148.174.143]) by sac.sfbay.sun.com (8.12.9+Sun/8.12.9) with ESMTP id j71FAKEu028919 for ; Mon, 1 Aug 2005 08:10:21 -0700 (PDT) Received: from phorcys.East.Sun.COM (localhost [127.0.0.1]) by phorcys.East.Sun.COM (8.13.4+Sun/8.13.4) with ESMTP id j71FAK9g010608 for ; Mon, 1 Aug 2005 11:10:20 -0400 (EDT) Received: (from carlsonj@localhost) by phorcys.East.Sun.COM (8.13.4+Sun/8.13.4/Submit) id j71FAK6M010605; Mon, 1 Aug 2005 11:10:20 -0400 (EDT) Date: Mon, 1 Aug 2005 11:10:20 -0400 (EDT) Message-Id: <200508011510.j71FAK6M010605@phorcys.East.Sun.COM> From: James Carlson To: psarc@sac.sfbay.sun.com Subject: 2005/430 Library Practice Clarification Status: RO Content-Length: 1368 This fast-track request timed out last Thursday, and as there were no objections, I've now marked it as "closed approved." The final text inserted into the BP document (amended to include the comments received) reads: NOTE that one instance in which a shared object containing only private interfaces may deliver an associated compilation environment name (and related materials, such as lint libraries and header files) is when the interfaces are to be used by a non-product (likely testing-related) delivery as part of the same project. The existence of such cases is the reason why this rule is just a warning. Databases that need to reference this exception case may refer to 'PSARC 2005/430' without requiring additional ARC review. NOTE that any human-readable files (e.g., include files) with private interfaces that can accept comments should have a warning against casual use of those interfaces. However, it is not ARC policy to require any ad-hoc obscuring of interfaces, such as symbol renaming or non-"lib" prefixes, unless a generic scoping mechanism is employed. -- James Carlson, KISS Network Sun Microsystems / 1 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677