[csw-devel] SF.net SVN: gar:[19669] csw/mgar/pkg/opencsw-manual/trunk/files
igalic at users.sourceforge.net
igalic at users.sourceforge.net
Sun Nov 11 19:06:16 CET 2012
Revision: 19669
http://gar.svn.sourceforge.net/gar/?rev=19669&view=rev
Author: igalic
Date: 2012-11-11 18:06:15 +0000 (Sun, 11 Nov 2012)
Log Message:
-----------
opencsw-manual/trunk: General review: fix formatting/spelling/wording
Modified Paths:
--------------
csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/getting-started.rst
csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/introduction.rst
csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/mirror-setup.rst
csw/mgar/pkg/opencsw-manual/trunk/files/for-developers/index.rst
csw/mgar/pkg/opencsw-manual/trunk/files/for-maintainers/filesystem-layout.rst
csw/mgar/pkg/opencsw-manual/trunk/files/for-maintainers/shared-libraries.rst
Modified: csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/getting-started.rst
===================================================================
--- csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/getting-started.rst 2012-11-11 15:49:54 UTC (rev 19668)
+++ csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/getting-started.rst 2012-11-11 18:06:15 UTC (rev 19669)
@@ -4,11 +4,11 @@
OpenCSW uses a tool named pkgutil_ on top of the Solaris packaging utilities to
automatically download, install and update packages. It needs to be installed
-manually once, after that all maintenance is done via pkgutil.
+manually once, after that all maintenance is done via ``pkgutil``.
.. _pkgutil: http://pkgutil.net
-On a Solaris 10 system, you can use the capacity of pkgadd to download
+On a Solaris 10 system, you can use the capacity of ``pkgadd`` to download
and install it via http in one step::
pkgadd -d http://get.opencsw.org/now
@@ -64,7 +64,7 @@
mirror=http://mirror.opencsw.org/opencsw/unstable
-By default, pkgutil is configured to use the ``testing`` catalog. You might
+By default, ``pkgutil`` is configured to use the ``testing`` catalog. You might
change it to ``unstable`` if you want to use newer versions of packages.
You can verify the setting with ``pkgutil -V``::
@@ -162,8 +162,8 @@
--------------------------------------------------------------
If you need to install a package with multiple dependencies on a host with no
-Internet access, you can use pkgutil to prepare a .pkg file with the whole
-dependency chain. This wasy is much easier than copying dependencies one by
+Internet access, you can use ``pkgutil`` to prepare a ``.pkg`` file with the
+whole dependency chain. This is much easier than copying dependencies one by
one::
pkgutil \
@@ -174,7 +174,7 @@
--download \
imagemagick coreutils vim ggrep gsed
-At the end of the run, pkgutil displays the correct order to install the
+At the end of the run, ``pkgutil`` displays the correct order to install the
packages in.
The resulting package stream will be placed in the ``~/.pkgutil/packages``
@@ -182,7 +182,4 @@
This topic is also `discussed`_ on the community site.
-.. _discussed:
- http://www.opencsw.org/community/
- questions/92/
- installing-without-a-direct-internet-access
+.. _discussed: http://www.opencsw.org/community/questions/92/installing-without-a-direct-internet-access
Modified: csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/introduction.rst
===================================================================
--- csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/introduction.rst 2012-11-11 15:49:54 UTC (rev 19668)
+++ csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/introduction.rst 2012-11-11 18:06:15 UTC (rev 19669)
@@ -3,8 +3,8 @@
------------
The world of open source is big. Although Solaris releases do contain the
-software companion disc, there's always more projects out there that can fit
-there.
+software companion disc, there's always more projects out there that can't
+fit there.
OpenCSW fills this gap by providing binary packages, together with their build
recipes. The packages can be installed comfortably with automatic dependency
Modified: csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/mirror-setup.rst
===================================================================
--- csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/mirror-setup.rst 2012-11-11 15:49:54 UTC (rev 19668)
+++ csw/mgar/pkg/opencsw-manual/trunk/files/for-administrators/mirror-setup.rst 2012-11-11 18:06:15 UTC (rev 19669)
@@ -2,21 +2,21 @@
Setting up a private mirror
---------------------------
-Sometimes it is sufficient to just go on with a mirror on the internet.
+Sometimes it is sufficient to simply use a mirror on the Internet.
However, there are situations where a local mirror can be useful. When you have
a lot of servers accessing the repository, want to control the package updates
-exactly or when your production servers just can't access the internet at all a
-local mirror is necessary.
+exactly or when your production servers just can't access the internet at all,
+a local mirror is necessary.
-To set up the mirror you should use rsync as it can update your local copy
+To set up the mirror you should use ``rsync`` as it can update your local copy
quickly and with low bandwidth use and also preserves hardlinks. Not all
-mirrors provide access via the rsync protocol, a list can be found at
+mirrors provide access via the ``rsync`` protocol, a list can be found at
http://www.opencsw.org/get-it/mirrors/ . To make a full copy of the OpenCSW
repository use this::
pkgutil -y -i rsync
rsync -aH --delete rsync://rsync.opencsw.org/opencsw /my/server/repo
-The directory ``repo`` can either be shared via HTTP or via NFS to the pkgutil
-clients. Use http://myserver/url-to-repo/ for HTTP and
-file:///myserver/dir-to-repo for NFS as mirror option in pkgutil.
+The directory ``repo`` can either be shared via HTTP or via NFS to the
+``pkgutil`` clients. Use http://myserver/url-to-repo/ for HTTP and
+file:///myserver/dir-to-repo for NFS as mirror option in ``pkgutil``.
Modified: csw/mgar/pkg/opencsw-manual/trunk/files/for-developers/index.rst
===================================================================
--- csw/mgar/pkg/opencsw-manual/trunk/files/for-developers/index.rst 2012-11-11 15:49:54 UTC (rev 19668)
+++ csw/mgar/pkg/opencsw-manual/trunk/files/for-developers/index.rst 2012-11-11 18:06:15 UTC (rev 19669)
@@ -12,8 +12,8 @@
relevant ``*_dev`` packages. They contain the header files, and ``*.so``
symlinks necessary during linking.
-When building againt OpenCSW software, these flags will typically make it
-work::
+When building againt OpenCSW software, aside from setting the ``PATH``
+correctly, these flags will typically make it work::
CPPFLAGS="-I/opt/csw/include"
LDFLAGS="-L/opt/csw/lib -R/opt/csw/lib"
Modified: csw/mgar/pkg/opencsw-manual/trunk/files/for-maintainers/filesystem-layout.rst
===================================================================
--- csw/mgar/pkg/opencsw-manual/trunk/files/for-maintainers/filesystem-layout.rst 2012-11-11 15:49:54 UTC (rev 19668)
+++ csw/mgar/pkg/opencsw-manual/trunk/files/for-maintainers/filesystem-layout.rst 2012-11-11 18:06:15 UTC (rev 19669)
@@ -12,14 +12,14 @@
The outermost installation directories are:
-* /opt/csw (base of the hierarchy)
-* /etc/opt/csw (configuration files)
-* /var/opt/csw (data files)
+* ``/opt/csw`` (base of the hierarchy)
+* ``/etc/opt/csw`` (configuration files)
+* ``/var/opt/csw`` (data files)
-The /opt/csw directory and everything below is considered read-only. It's
-a common practice to set up non-global sparse zones with shared /opt/csw. In
-this setup, non-global zones see /opt/csw as mounted read-only. Any local
-state needs to be kept under /var/opt/csw.
+The ``/opt/csw`` directory and everything below is considered read-only. It's
+a common practice to set up non-global sparse zones with shared ``/opt/csw``.
+In this setup, non-global zones see ``/opt/csw`` as mounted read-only. Any
+local state needs to be kept under ``/var/opt/csw``.
.. [#shared-opt-csw]
`Shared /opt/csw configuration files`_
Modified: csw/mgar/pkg/opencsw-manual/trunk/files/for-maintainers/shared-libraries.rst
===================================================================
--- csw/mgar/pkg/opencsw-manual/trunk/files/for-maintainers/shared-libraries.rst 2012-11-11 15:49:54 UTC (rev 19668)
+++ csw/mgar/pkg/opencsw-manual/trunk/files/for-maintainers/shared-libraries.rst 2012-11-11 18:06:15 UTC (rev 19669)
@@ -23,23 +23,23 @@
shared libraries became available upstream, updated packages included
both old and new versions of shared libraries. This required package
builds to download and compile multiple versions of the same project.
-Notable examples are curl and neon libraries, where CSWcurlrt contained
-all three libcurl.so.2, libcurl.so.3 and libcurl.so.4.
+Notable examples are curl and neon libraries, where ``CSWcurlrt`` contained
+all three ``libcurl.so.2``, ``libcurl.so.3`` and ``libcurl.so.4``.
Phasing out of shared libraries was difficult. To phase out a shared
library, it is required to verify that no binaries link to it. All
dependent packages need to be recompiled against the newest version of
the library, and once this is done, old versions can be removed.
However, even when all dependent packages are already recompiled against
-libcurl.so.4, there are no useful indicators that libcurl.so.2 is no
-longer linked to. To verify this, all dependent packages have to be
-unpacked, and examined using /usr/ccs/bin/dump that they no longer list
-libcurl.so.2 in their NEEDED field.
+``libcurl.so.4``, there are no useful indicators that ``libcurl.so.2`` is
+no longer linked to. To verify this, all dependent packages have to be
+unpacked, and examined using ``/usr/ccs/bin/dump`` that they no longer
+list ``libcurl.so.2`` in their ``NEEDED`` field.
Once the detection problem is solved, removing the old version of
-a library is not as simple as it could be; The whole CSWcurlrt has to be
-rebuilt and re-released in a new version which no longer includes
-libcurl.so.2.
+a library is not as simple as it could be; The whole ``CSWcurlrt`` has
+to be rebuilt and re-released in a new version which no longer includes
+``libcurl.so.2``.
Goals
-----
@@ -48,20 +48,20 @@
* Allowing to determine whether a specific shared library is no longer
linked to, by looking at package dependencies (This avoids potential
problem of our keeping "legacy binary libs" in a more modern package
- for longer than is neccessary. It also avoids having to keep coping
+ for longer than is necessary. It also avoids having to keep coping
the binary into future packages)
Non-goals
---------
-* Providing a reliable mechanism to determine whether a given pkgname
- contains a shared library
+* Providing a reliable mechanism to determine whether a given package
+ name contains a shared library
* Keeping package names short and pretty as a priority
Overview
--------
-As a general rule, each soname shall be packaged in a separate package.
+As a general rule, each SONAME shall be packaged in a separate package.
This way, it's easy to track dependencies on specific sonames, detect
and phase out sonames that are no longer in use. It also avoids the
need to rebuild all the versions of software in question if one of the
@@ -79,14 +79,14 @@
* simpler packages, simpler builds (no need for version modulations and
complex merges, good for new maintainers)
* isolation of old non-fixable files with issues (if there's an old
- library mentioning /export/medusa, you don't have to worry about it
+ library mentioning ``/export/medusa``, you don't have to worry about it
being stopped during release after you push it once)
* no re-pushing of old files
* more packages overall (good for stats!)
* number of packages released per software upgrade remains the same. If
there were, say, 4 packages to release with each Python update, the
- number remains: 4 per release. There will be one new CSWlibpython*
- package, and the old CSWlibpython library won't be upgraded.
+ number remains: 4 per release. There will be one new ``CSWlibpython*``
+ package, and the old ``CSWlibpython`` library won't be upgraded.
Disadvantages:
@@ -102,31 +102,31 @@
Package naming
~~~~~~~~~~~~~~
-Names of packages shall be derived from sonames, and from sonames only.
+Names of packages shall be derived from SONAMEs, and from SONAMEs only.
They shall not depend on project name, or project version. If a project
-is named foo, and contains libbar.so.0, the package name shall be based
-on libbar, not foo.
+is named ``foo``, and contains ``libbar.so.0``, the package name shall be
+based on ``libbar``, not ``foo``.
-A table listing examples of sonames and corresponding package
+A table listing examples of SONAMEs and corresponding package
names. [#soname-pkgname-unit-test]_
-========================= ======================= =========================
-soname pkgname catalogname
-========================= ======================= =========================
-libfoo.so.0 CSWlibfoo0 libfoo0
-libfoo-0.so CSWlibfoo0 libfoo0
-libfoo.so.0.1 CSWlibfoo0-1 libfoo0_1
-libapr-1.so.0 CSWlibapr1-0 libapr1_0
-libbabl-0.1.so.0 CSWlibbabl0-1-0 libbabl0_1_0
-libgettextlib-0.14.1.so CSWlibgettextlib0-14-1 libgettextlib0_14_1
-libapr-1.so.10 CSWlibapr-1-10 libapr_1_10
-libstdc++.so.6 CSWlibstdc++6 libstdc++6
-libdnet.1 CSWlibdnet1 libdnet1
-libUpperCase.so.1 CSWlibuppercase1 libuppercase1
-libpyglib-2.0-python.so.0 CSWlibpyglib2-0python0 libpyglib2_0python0
-libpython3.1.so.1.0 CSWlibpython3-1-1-0 libpython3_1_1_0
-libapr-1.so.10.0.0 CSWlibapr1-10-0-0 libapr1_10_0_0
-========================= ======================= =========================
+============================= =========================== ===========================
+SONAME package name catalog name
+============================= =========================== ===========================
+``libfoo.so.0`` ``CSWlibfoo0`` ``libfoo0``
+``libfoo-0.so`` ``CSWlibfoo0`` ``libfoo0``
+``libfoo.so.0.1`` ``CSWlibfoo0-1`` ``libfoo0_1``
+``libapr-1.so.0`` ``CSWlibapr1-0`` ``libapr1_0``
+``libbabl-0.1.so.0`` ``CSWlibbabl0-1-0`` ``libbabl0_1_0``
+``libgettextlib-0.14.1.so`` ``CSWlibgettextlib0-14-1`` ``libgettextlib0_14_1``
+``libapr-1.so.10`` ``CSWlibapr-1-10`` ``libapr_1_10``
+``libstdc++.so.6`` ``CSWlibstdc++6`` ``libstdc++6``
+``libdnet.1`` ``CSWlibdnet1`` ``libdnet1``
+``libUpperCase.so.1`` ``CSWlibuppercase1`` ``libuppercase1``
+``libpyglib-2.0-python.so.0`` ``CSWlibpyglib2-0python0`` ``libpyglib2_0python0``
+``libpython3.1.so.1.0`` ``CSWlibpython3-1-1-0`` ``libpython3_1_1_0``
+``libapr-1.so.10.0.0`` ``CSWlibapr1-10-0-0`` ``libapr1_10_0_0``
+============================= =========================== ===========================
Separators are added between two adjacent numbers, and removed if a number and
a letter are next to each other. For example, ``libfoo.so.0`` becomes
@@ -137,30 +137,30 @@
The policy or recommendation shall refer to libraries which are //linkable,//
meaning other binaries can link against them. Shared objects in private
-directories, such as /opt/csw/lib/someproject/foo.so (think Python modules)
+directories, such as ``/opt/csw/lib/someproject/foo.so`` (think Python modules)
are not shared libraries which other projects can link to, and therefore there
is no benefit in placing them in separate packages.
Some packages (e.g. Kerberos libraries) put private shared libraries into
-/opt/csw/lib. They don't expose any public API, and only own Kerberos
+``/opt/csw/lib``. They don't expose any public API, and only own Kerberos
binaries link to them. Private shared libraries can be bundled with the main
package, without splitting them off.
-============================================================================== ============
-file linkable?
-============================================================================== ============
-/opt/csw/lib/libfoo.so.0.2 Yes
-/opt/csw/lib/sparcv9/libfoo.so.0.2 Yes
-/opt/csw/lib/sparcv8plus+vis/libfoo.so.0.2 Yes
-/opt/csw/lib/amd64/libfoo.so.0.2 Yes
-/opt/csw/libexec/bar No
-/opt/csw/share/bar No
-/opt/csw/lib/gnucash/libgncmod-stylesheets.so.0.0.0 No
-/opt/csw/lib/erlang/lib/megaco-3.6.0.1/priv/lib/megaco_flex_scanner_drv_mt.so No
-/opt/csw/share/Adobe/Reader8/Reader/sparcsolaris/lib/libcrypto.so.0.9.6 No
-/opt/csw/customprefix/lib/libfoo.so.0.2 Yes
-/opt/csw/boost-gcc/lib/libboost_wserialization.so.1.44.0 Yes
-============================================================================== ============
+================================================================================ ============
+file linkable?
+================================================================================ ============
+``/opt/csw/lib/libfoo.so.0.2`` Yes
+``/opt/csw/lib/sparcv9/libfoo.so.0.2`` Yes
+``/opt/csw/lib/sparcv8plus+vis/libfoo.so.0.2`` Yes
+``/opt/csw/lib/amd64/libfoo.so.0.2`` Yes
+``/opt/csw/libexec/bar`` No
+``/opt/csw/share/bar`` No
+``/opt/csw/lib/gnucash/libgncmod-stylesheets.so.0.0.0`` No
+``/opt/csw/lib/erlang/lib/megaco-3.6.0.1/priv/lib/megaco_flex_scanner_drv_mt.so`` No
+``/opt/csw/share/Adobe/Reader8/Reader/sparcsolaris/lib/libcrypto.so.0.9.6`` No
+``/opt/csw/customprefix/lib/libfoo.so.0.2`` Yes
+``/opt/csw/boost-gcc/lib/libboost_wserialization.so.1.44.0`` Yes
+================================================================================ ============
Example implementation and its unit tests can be found in checkpkg
sources [#is-library-linkable-implementation]_ and corresponding unit
@@ -202,9 +202,9 @@
There can be cases in which a set of shared libraries is likely to be
upgraded together. Considering the following set of libraries:
-* libfoo.so.0
-* libfoo_bar.so.0
-* libfoo_baz.so.0
+* ``libfoo.so.0``
+* ``libfoo_bar.so.0``
+* ``libfoo_baz.so.0``
It's possible that all the following libraries will be updated together.
In such a case, all these shared objects can be put in a single package.
@@ -215,9 +215,9 @@
together. For example, the following three libraries are best kept in
separate packages.
-* libfoo.so.0
-* libfoo_bar.so.1
-* libfoo_baz.so.0
+* ``libfoo.so.0``
+* ``libfoo_bar.so.1``
+* ``libfoo_baz.so.0``
When making the decision, the question a maintainer should ask, should
be: "Are all these shared libraries going to be retired together?" If
@@ -237,30 +237,30 @@
* Before
- - CSWlibfoo (libfoo.so.1)
+ - ``CSWlibfoo`` (``libfoo.so.1``)
* After
- - CSWlibfoo (empty) → CSWlibfoo1 (libfoo.so.1)
+ - ``CSWlibfoo`` (empty) → ``CSWlibfoo1`` (``libfoo.so.1``)
For an existing more complex package, with already existing two versions
of a library:
* Before
- - CSWlibfoo (libfoo.so.1, libfoo.so.2)
+ - ``CSWlibfoo`` (``libfoo.so.1``, ``libfoo.so.2``)
* After
- - CSWlibfoo (empty) → CSWlibfoo1 (libfoo.so.1)
- - CSWlibfoo (empty) → CSWlibfoo2 (libfoo.so.2)
+ - ``CSWlibfoo`` (empty) → ``CSWlibfoo1`` (``libfoo.so.1``)
+ - ``CSWlibfoo`` (empty) → ``CSWlibfoo2`` (``libfoo.so.2``)
Potential problems
==================
-Potential collisions in package naming would include libfoo.so.1 and
-libfoo-1.so both resolving to CSWlibfoo1. If this case ever occurs, the
-naming conflict needs to be resolved manually. However, to this time,
+Potential collisions in package naming would include ``libfoo.so.1`` and
+``libfoo-1.so`` both resolving to ``CSWlibfoo1``. If this case ever occurs,
+the naming conflict needs to be resolved manually. However, to this time,
such a case has been never observed.
Certain sonames are long enough that the corresponding package names are
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the devel
mailing list