[csw-devel] SF.net SVN: gar:[12157] csw/mgar/pkg
wahwah at users.sourceforge.net
wahwah at users.sourceforge.net
Mon Jan 3 15:14:24 CET 2011
Revision: 12157
http://gar.svn.sourceforge.net/gar/?rev=12157&view=rev
Author: wahwah
Date: 2011-01-03 14:14:24 +0000 (Mon, 03 Jan 2011)
Log Message:
-----------
opencsw-policy: Initial commit
An example page written in asciidoc. The purpose is to review the language on
the mailing list.
http://lists.opencsw.org/pipermail/maintainers/2011-January/013615.html
Modified Paths:
--------------
csw/mgar/pkg/opencsw-policy/trunk/Makefile
csw/mgar/pkg/opencsw-policy/trunk/checksums
Added Paths:
-----------
csw/mgar/pkg/opencsw-policy/
csw/mgar/pkg/opencsw-policy/trunk/files/index.txt
csw/mgar/pkg/opencsw-policy/trunk/files/shared-csw-opt.txt
Modified: csw/mgar/pkg/opencsw-policy/trunk/Makefile
===================================================================
--- csw/mgar/pkg/template/trunk/Makefile 2010-12-15 04:27:05 UTC (rev 11951)
+++ csw/mgar/pkg/opencsw-policy/trunk/Makefile 2011-01-03 14:14:24 UTC (rev 12157)
@@ -2,184 +2,43 @@
# Distributed under the terms of the GNU General Public License v2
# $Id$
-## This file contains comments to guide you through various GAR settings.
-## Please remove unnecessary comments before committing your code to the code
-## repository. The comments to remove are marked with double hashes.
-## If you want to remove them all in-place, use:
-## gsed -i -e '/^##/d' Makefile
-##
-## For more information about GAR variables, please see:
-## https://sourceforge.net/apps/trac/gar/wiki/GAR%20Variable%20Reference
-##
-NAME = mypkg
-VERSION = 1.0
-##
-## The category that your software fits in. This is not a descriptive field, but
-## influences the build process. Depending on the CATEGORIES setting, different
-## Makefiles are included from gar/categories/ in your trunk directory, which
-## adjust the build settings for the respective category.
-##
-## Possible settings are:
-## apps, cpan, devel, gnome, java, kde, lang, lib, meta, net, python, server,
-## utils, x11, xfce, xorg, xtra
+NAME = opencsw-policy
+VERSION = 0.1
CATEGORIES = lib
-##
-## A one-line description of the package, which will appear in the pkginfo.
-DESCRIPTION = <please fill in>
-##
-## A longer description of the package. This is only for descriptive purposes
-## inside the Makefile and is not used elsewhere.
+DESCRIPTION = OpenCSW packaging policy
define BLURB
- <please fill in>
endef
-##
-## Upstream URL that should show up in the VENDOR field as well as on
-## http://opencsw.org/packages/<packagename>.
-SPKG_SOURCEURL =
-##
-## Whitespace-separated list of URLs to download the source package from.
-## There are presets: $(SF_MIRRORS), $(GNU_MIRRORS) and $(GOOGLE_MIRROR).
-MASTER_SITES =
-##
-## SF_PROJ is required if you set $(MASTER_SITES) to $(SF_MIRRORS) and the
-## Sourceforge project name differs from $(NAME). Specifies the Sourceforge
-## project name of the software you wish to download.
-## SF_PROJ =
-##
-## A list of space separated patch filenames from files/ that are to be applied
-## to the extracted software before the ./configure stage. Patches need to be
-## included in the DISTFILES variable as well.
-## PATCHFILES =
-##
-## Whitespace-separated list of files which comprise this build. mGAR will look
-## for the files in the $(FILEDIR) (trunk/files) directory and on the
-## $(MASTER_SITES).
-DISTFILES = $(NAME)-$(VERSION).tar.gz
-##
-## We define upstream file regex so we can be notifed of new upstream software release
-UFILES_REGEX = $(NAME)-(\d+(?:\.\d+)*).tar.gz
-##
-## Catalog name is the name to be used with pkg{-get,util} -i <pkgname>.
-## It is different from the system package name, which by convention is CSWpkgname.
-## CATALOGNAME =
-##
-## Set to 1 to mark the package as architecture-independent.
-## ARCHALL = 0
-##
-## A list of files / patterns that should be excluded from the package. Amends
-## the default list of excluded filenames $(MERGE_EXCLUDE_DEFAULT), which
-## contains things like libtool .la files and files with a leading ~.
-## EXTRA_MERGE_EXCLUDE_FILES =
-##
-## A list of space separated package names that should be marked as
-## incompatible with the current package. This will go into the depend file.
-## When a user has one of the incompatible packages installed and installs
-## your package, he will be prompted that the incompatible package must be
-## removed. He will however not be prevented to install your package without
-## removing the conflicting package first.
-## INCOMPATIBLE_PKGS =
-##
-## The name of the license file that should be included in your package. Defaults
-## to COPYING. See http://sourceforge.net/apps/trac/gar/wiki/CopyRightfor details
-## on including and displaying licenses.
-## LICENSE =
-##
-## A list of space separated package names that should be produced from your
-## Makefile. This is used when a software has different components that can be
-## packaged and used individually (think runtime libraries, client tools, server
-## files, development headers). You don't need to set this when you just want to
-## produce one package.
-##
-## When you set this variable to include more than one package, you also need to
-## set PKGFILES_CSWpkgname for each package (except for the first one in your
-## $(PACKAGES) list) to define which files go into each package. The first
-## package from $(PACKAGES) one will hold all files that are not matched by
-## PKGFILES_ for other packages.
-## PACKAGES =
-##
-## If specified, GAR feeds the almost-final package prototype file to
-## $(PROTOTYPE_FILTER) and reads the final package prototype file from it.
-## $(PROTOTYPE_FILTER) is usually a sed/awk/perl one-liner, which was mostly used
-## to prepare the prototype file for use with cswclassutils (see
-## $(SPKG_CLASSES)). Now that there are convenience variables for cswclassutils,
-## you will rarely have to use this. A still valid use case would be to change
-## the file permissions of a file to be set-UID.
-## See http://wiki.opencsw.org/cswclassutils-package for common usage information
-## PROTOTYPE_FILTER =
-##
-## cswclassutils settings
-##
-## A list of action classes. Possible values are:
-## none cswpreserveconf cswcpsampleconf cswpycompile cswusergroup cswinitsmf
-## cswinetd cswetcservices
-## The class 'cswinitsmf' must be the last class listed. When you use cswclassutils,
-## you need to add CSWcswclassutils to RUNTIME_DEP_PKGS.
-## SPKG_CLASSES = none
-## Simplified settings for classes:
-## PRESERVECONF =
-## SAMPLECONF =
-## INITSMF =
-## USERGROUP =
-## ETCSERVICES = <file containing an entry for /etc/services>
-## INETDCONF = <file containing an inetd.conf formatted entry>
-## A list of runtime package dependencies in the form of CSWfoo.
-## RUNTIME_DEP_PKGS =
-##
-## A list of packages necessary to build this package
-## BUILD_DEP_PKGS = $(RUNTIME_DEP_PKGS)
-##
-## When using non-empty $(PACKAGES):
-## RUNTIME_DEP_PKGS_CSWpkgname =
-## SPKG_DESC_CSWpkgname =
-## PKGFILES_CSWpkgname =
-## CATALOGNAME_CSWpkgname =
-##
-## A list of space separated directories where objects should be stripped in
-## addition to the bin/ and sbin/ directories.
-## STRIP_DIRS =
-##
-## Define a custom target for the configure phase. When you set this, the target
-## that will be used instead of configure: target, is named
-## configure-$(CONFIGURE_SCRIPTS) and you will need to define it in your Makefile
-## after including gar/gar.include.mk. If you want to skip the configure phase
-## completely (for example when your software doesn't need to be compiled) assign
-## this variable an empty value. The procedure works for configure, build,
-## install and test steps.
-## CONFIGURE_SCRIPTS =
-## BUILD_SCRIPTS =
-## INSTALL_SCRIPTS =
-## TEST_SCRIPTS =
-##
-## Compilation settings
-##
-## The build directory.
-## WORKSRC = $(WORKDIR)/$(NAME)-$(VERSION)
-##
-## BUILD_ARGS is passed as an argument to gmake during the build phase. Use this
-## for example, if you need to override Makefile variables.
-## BUILD_ARGS =
-##
-## Arguments passed to the ./configure script.
-CONFIGURE_ARGS = $(DIRPATHS)
-##
-## BUILD64 =
-## CONFIGURE_ENV =
-## EXTRA_CFLAGS =
-## EXTRA_LDFLAGS =
-## EXTRA_INC =
-## EXTRA_LIB =
-## GARFLAVOR =
-## INSTALL_ARGS =
-## OPT_FLAGS_SOS = -xO3
-## OPT_FLAGS_GCC = -O2 -pipe
-##
-## The compiler to use. Defaults to SOS11, can be also: SOS12, GCC3, GCC4.
-## GARCOMPILER = SOS11
-##
-# Remove the following rules and uncomment the
-# include before building.
-all: .DEFAULT
-.DEFAULT:
- @true
+SPKG_SOURCEURL = http://www.opencsw.org
+MASTER_SITES = http://www.gnu.org/licenses/
+DISTFILES = fdl-1.3.txt
+CONFIGURE_SCRIPTS =
+BUILD_SCRIPTS = policy
+INSTALL_SCRIPTS = policy
+TEST_SCRIPTS =
+ARCHALL_CSWopencsw-policy = 1
+CATALOGNAME_CSWopencsw-policy = opencsw_policy
+LICENSE = fdl-1.3.txt
-#include gar/category.mk
+BUILD_DEP_PKGS = CSWasciidoc
+
+include gar/category.mk
+
+%.html: %.txt
+ asciidoc -o $@ $<
+
+build-policy: \
+ copy-asciidoc \
+ $(WORKSRC)/index.html
+
+copy-asciidoc:
+ gcp -v $(FILEDIR)/*.txt $(WORKSRC)
+
+install-policy:
+ ginstall -m 755 -d $(PKGROOT)$(docdir)/$(CATALOGNAME_CSWopencsw-policy)
+ for f in $(WORKSRC)/*.html $(WORKSRC)/*.txt; do \
+ ginstall $${f} $(PKGROOT)$(docdir)/$(CATALOGNAME_CSWopencsw-policy); \
+ done
+ @$(MAKECOOKIE)
+
+post-merge:
+ cp $(PKGROOT)/opt/csw/share/doc/opencsw_policy/index.html $(HOME)/public_html/policy || true
Modified: csw/mgar/pkg/opencsw-policy/trunk/checksums
===================================================================
--- csw/mgar/pkg/template/trunk/checksums 2010-12-15 04:27:05 UTC (rev 11951)
+++ csw/mgar/pkg/opencsw-policy/trunk/checksums 2011-01-03 14:14:24 UTC (rev 12157)
@@ -0,0 +1 @@
+10b9de612d532fdeeb7fe8fcd1435cc6 fdl-1.3.txt
Added: csw/mgar/pkg/opencsw-policy/trunk/files/index.txt
===================================================================
--- csw/mgar/pkg/opencsw-policy/trunk/files/index.txt (rev 0)
+++ csw/mgar/pkg/opencsw-policy/trunk/files/index.txt 2011-01-03 14:14:24 UTC (rev 12157)
@@ -0,0 +1,9 @@
+OpenCSW packaging policy
+========================
+$Id: Makefile 11888 2010-12-12 12:43:48Z skayser $
+:toc:
+:website: http://www.opencsw.org
+
+:leveloffset: 1
+
+include::shared-csw-opt.txt[]
Added: csw/mgar/pkg/opencsw-policy/trunk/files/shared-csw-opt.txt
===================================================================
--- csw/mgar/pkg/opencsw-policy/trunk/files/shared-csw-opt.txt (rev 0)
+++ csw/mgar/pkg/opencsw-policy/trunk/files/shared-csw-opt.txt 2011-01-03 14:14:24 UTC (rev 12157)
@@ -0,0 +1,169 @@
+Shared /opt/csw
+===============
+
+When creating packages that require configuration files, or startup
+information, etc. it is important to be aware that some sites may deploy their
+systems with a shared /opt/csw across multiple machines.
+
+There are a few different variants of this. Among them are:
+
+* NFS-shared /opt/csw, shared read-only across multiple machines
+* /opt/csw duplicated via rsync or other means
+* A filesystem shared across multiple zones
+* A filesystem shared across multiple "Boot Environments" on the same machine
+ (a la "beadm")
+
+
+There are multiple reasons why a site may choose to go this route. One may be
+that it is a heterogenous environment, and a central NFS server is simply
+their standard way of sharing things out. One central file server, means one
+and only central place to do backups, etc.
+
+Another reason may be: when you have a high number of zones on a box, having
+every single pkgadd go through each zone and do the strange
+child-zone-specific pkgadd/pkgrm, is too aggravating to deal with. So they may
+choose to have /opt/csw be a NON-"inherit-pkg-dir" mount from the global zone.
+Or, they may choose to not add packages in the global zone at all! but allow
+one zone to be the csw package master, and then share /opt/csw from that zone,
+to other zones.
+
+The good news for maintainers is, we dont need to know the specifics of each
+site configuration. We can service any and all of the above cases quite
+nicely, by following some basic principles.
+
+Yes, this unfortunately may mean more work for the maintainer! But this is
+a major reason for people to value OpenCSW packages, over just a blind
+"compile and install" approach.
+
+Categories of packaging challege
+--------------------------------
+
+All software to be packaged will most likely fall into one, or sometimes two, of the following categories:
+
+* Standalone tools - No config needed!
+* Machine-individual configuration/data always required
+* Configuration "required", but almost always the same on ANYONE's site
+* Daemons
+* Programs that already are, or can be made to be, dual config (one global in /opt/csw/etc, and one in /etc/opt/csw)
+* Optional configuration
+
+Lets address each of these one by one
+
+Standalone tools
+~~~~~~~~~~~~~~~~
+
+Congratulations you lucky person! You're done here!
+
+Machine-individual configuration always required
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Okay, some things (such as databases) always need a local configuration to
+work. If you are nice, you may have provided some kind of postinstall script
+to automate this as much as possible. However, NFS-shared type sites, dont
+automatically get the postinstall run on each machine! At minimum, you need
+to provide documentation (under our normal location of
+/opt/csw/share/progname/) of what is required to get the software properly
+working on each individual machine. Ideally, you would create some kind of
+auto-install script, that can be called EITHER by postinstall, OR by hand, on
+an individual machine that has nothing but /opt/csw mounted.
+
+
+Configuration "required", but almost always the same
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're really really REALLY sure that no sane person will ever edit the
+config file, it might be okay to put it directly in /opt/csw/etc and be done
+with it. However, the "right" way to handle this would be to put your expected
+config as a template, /opt/csw/etc/yourprog.conf.CSW, and then use one of our
+"cswclassutils" to automatically install and remove it to the normal place, IF
+the site admin has not chosen to make local tweaks. That's it! You're done
+here.
+
+Daemons
+~~~~~~~
+
+A lot to talk about here. As far as configs go, you could start by treating
+them as the "machine local config always required" case, but there are
+additional considerations. You really need to read the full Daemon
+configuration page.
+
+Programs that already are, or can be made to be, dual config
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Happily, some enterprise-level software is already capable of having both
+a "global" and a "local" set of configs. In this case, your task is easy.
+Create the default global ones (ideally by following the steps in the "always
+the same" item, above), and then provide sample local config files as
+appropriate. Possibly, your template global config
+file(/opt/csw/etc/prog.conf.CSW) will serve fine for this as well. If so, make
+sure to comment that fact in your template one. There are some programs that
+do not act this way "out of the box", but can be made to act this way, with
+appropriate tweaks. For example, some programs allow for an optional
+"include" syntax, that will pull in an extra config file if present, but not
+complain too much if it is not there. In these cases, take advantage of this
+syntax in the global file, and ship it as a dual config style package.
+
+
+Optional configuration
+~~~~~~~~~~~~~~~~~~~~~~
+
+Some programs can "allow for" a local configuration, but can still run with
+a reasonable set of defaults. If your program is in this category (or at least
+can be MADE to fit in this category), then *just make sure that "it runs", if
+nothing outside of /opt/csw gets distributed.* Put information in our usual
+location of /opt/csw/share/progname/ of how to add in local tweaks. Provide
+sample configs, or a setup script if appropriate.
+
+Summary of acceptable directory use
+-----------------------------------
+
+It's possible to share the /opt/csw directory among multiple Solaris zones, or
+among multiple systems, using NFS. Such setup required paying attention to
+some details. In the case of sharing /opt/csw among sparse non-global Solaris
+zones, the /opt/csw directory is going to be read-only. Some programs are
+going to need separate configuration files, or a separate state keeping
+directory. To have this setup working, one needs:
+
+[options="header"]
+|===============================================================================
+| | directory | writable | Allowable use
+| 1. | /opt/csw | No | Non-changable files, with exceptions below
+| 2. | /opt/csw**/var** | No | *Never use this*
+| 3. | /opt/csw**/etc** | (special) |
+Use for template files(packaged), and global configs (postinstall/classutil)
+generated from template files
+
+| 4. | **/var**/opt/csw | *Yes* |
+Allowable for *run-time-only* data. Do not deliver files in package here
+
+| 5. | **/etc**/opt/csw | *Yes* |
+Optional site-admin, or template-copied, configs only. No "packaged" files
+
+|===============================================================================
+
+Note that for #3, if you have a postinstall or class action script generating
+content in /opt/csw/etc, it must fail gracefully if /opt/csw is read-only.
+
+A very few, ancient packages are still using the /opt/csw/var and
+/opt/csw/etc directories and may not work correctly. There's ongoing work
+to update them to use the correct directories.
+
+GAR tweaks to set autoconf progs to use local /etc
+--------------------------------------------------
+
+For the case of "Machine-individual configuration always required", in GAR,
+only the two following variables need to be set, usually:
+
+.GAR configuration sample
+--------------------------------------------------------------------------------
+localstatedir = /var$(prefix)
+sysconfdir = /etc$(prefix)
+--------------------------------------------------------------------------------
+
+There are actually standard GNU autoconf (configure) settings, which will be passed on.
+
+See also
+--------
+
+* Configuration directory migration
+* http://www.opencsw.org/userguide/sharingcsw[Sharing /opt/csw] at opencsw.org
Property changes on: csw/mgar/pkg/opencsw-policy/trunk/files/shared-csw-opt.txt
___________________________________________________________________
Added: svn:keywords
+ Id
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