From 6e020db5a2a983e7406d50df2bd0daecc514979c Mon Sep 17 00:00:00 2001 From: Keith Marshall Date: Fri, 11 Mar 2011 20:22:30 +0000 Subject: [PATCH] Refactor and update existing installation and usage instructions. --- ChangeLog | 26 ++++ Makefile.in | 58 ++++++-- README | 351 ---------------------------------------------- src/clistub.c | 19 ++- srcdist-doc/INSTALL.in | 295 ++++++++++++++++++++++++++++++++++++++ srcdist-doc/NEWS.in | 227 ++++++++++++++++++++++++++++++ srcdist-doc/README.in | 67 +++++++++ srcdist-doc/gendoc.sed.in | 106 ++++++++++++++ 8 files changed, 782 insertions(+), 367 deletions(-) delete mode 100644 README create mode 100644 srcdist-doc/INSTALL.in create mode 100644 srcdist-doc/NEWS.in create mode 100644 srcdist-doc/README.in create mode 100644 srcdist-doc/gendoc.sed.in diff --git a/ChangeLog b/ChangeLog index d067485..1107db7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,29 @@ +2011-03-11 Keith Marshall + + Refactor and update existing installation and usage instructions. + + * src/clistub.c (help_text): Updated. + + * srcdist-doc: New directory. + + * README: Deleted; its content refactored into... + * srcdist-doc/README.in srcdist-doc/INSTALL.in srcdist-doc/NEWS.in: + ...these new template files, updated for current development state. + + * srcdist-doc/gendoc.sed.in: New sed script; it directs formatting of + generated text files derived from the srcdist-doc templates. + + * Makefile.in (SRCDIST_SUBDIRS): Add srcdist-doc. + (SRCDIST_FILES): Add NEWS and INSTALL. + (srcdist-doc): New build rule to generate README, NEWS and INSTALL. + (srcdist, licdist): Adjust path to locate them. + (readme.txt): New build rule to generate on-line package description. + (dist): Require it. + (distclean): Don't remove Makefile... + (maintainer-clean): ...but do it here instead. Also remove generated + README, NEWS and INSTALL, the autom4te cache, and all distributable + zip files, in addition to tarballs, for the current version. + 2011-02-27 Keith Marshall Initial implementation for "remove" feature. diff --git a/Makefile.in b/Makefile.in index ead2b38..ddcea8c 100644 --- a/Makefile.in +++ b/Makefile.in @@ -152,10 +152,10 @@ install-strip: install # Packaging and distribution... # LICENCE_FILES = README COPYING -SRCDIST_FILES = $(LICENCE_FILES) ChangeLog \ +SRCDIST_FILES = $(LICENCE_FILES) ChangeLog NEWS INSTALL \ aclocal.m4 configure.ac configure Makefile.in version.c.in -SRCDIST_SUBDIRS = build-aux m4 src src/pkginfo tinyxml xml +SRCDIST_SUBDIRS = build-aux m4 src src/pkginfo srcdist-doc tinyxml xml # The names of distributed pacakge archive files incorporate version # information, derived from PACKAGE_VERSION; this is decomposed, so that @@ -174,7 +174,7 @@ PACKAGE_DISTVERSION = `echo $(PACKAGE_VERSION)-$(PACKAGE_SUBSYSTEM) | sed \ -e 's,-$(PACKAGE_SUBSYSTEM),$(SNAPSHOT)&,'` PACKAGE_DISTNAME = $(PACKAGE_TARNAME)-$(PACKAGE_DISTVERSION) -dist: srcdist bindist +dist: srcdist bindist readme.txt bindist: all licdist rm -rf staged @@ -190,14 +190,20 @@ licdist: rm -rf share $(mkinstalldirs) ./share/doc/${PACKAGE_TARNAME} cd ./share/doc/${PACKAGE_TARNAME}; for file in $(LICENCE_FILES); \ - do $(LN_S) ${abs_top_srcdir}/$$file .; done + do test -f ${abs_top_srcdir}/$$file \ + && $(LN_S) ${abs_top_srcdir}/$$file . \ + || $(LN_S) ../$$file .; \ + done tar chf - share | gzip -c > $(PACKAGE_DISTNAME)-lic.tar.gz rm -rf share -srcdist: pkginfo.c +srcdist: pkginfo.c srcdist-doc rm -rf ${PACKAGE_DISTROOT} && mkdir ${PACKAGE_DISTROOT} cd ${PACKAGE_DISTROOT}; for file in $(SRCDIST_FILES); do \ - $(LN_S) ${abs_top_srcdir}/$$file .; done + test -f ${abs_top_srcdir}/$$file \ + && $(LN_S) ${abs_top_srcdir}/$$file . \ + || $(LN_S) ../$$file .; \ + done for dir in $(SRCDIST_SUBDIRS); do \ mkdir ${PACKAGE_DISTROOT}/$$dir && cd ${PACKAGE_DISTROOT}/$$dir; \ for file in `cd ${abs_top_srcdir}/$$dir && echo *`; do \ @@ -210,16 +216,50 @@ srcdist: pkginfo.c tar chf - ${PACKAGE_DISTROOT} | gzip -c > ${PACKAGE_DISTNAME}-src.tar.gz rm -rf ${PACKAGE_DISTROOT} +# README, INSTALL and NEWS files to be included in the source distribution +# are generated on demand, as indirect side effects of a set of phoney goals +# so that they are always regenerated for each distribution, from templates +# in srcdist-doc so that we can make them version specific. +# +vpath %.in ${srcdir}/srcdist-doc +srcdist-doc: README.dist NEWS.dist INSTALL.dist + +%.dist: %.in gendoc.simple.sed + sed -f gendoc.simple.sed $< | nroff > $* + +%.simple.sed: %.sed.in + sed -e s,'$${PACKAGE_DIRNAME}',"${PACKAGE_DISTROOT}", \ + -e s,'$${PACKAGE_DISTNAME}',"${PACKAGE_DISTNAME}", $< > $@ + +%.combined.sed: %.sed.in + sed -e s,'$${PACKAGE_DIRNAME}',"${PACKAGE_DISTROOT}", \ + -e s,'$${PACKAGE_DISTNAME}',"${PACKAGE_DISTNAME}", \ + -e s,'^# *cut:',, $< > $@ + +# The following rule provides a mechanism for generating a composite from +# README, INSTALL and NEWS, for use as an on-line package description. +# +readme.txt: README.in NEWS.in INSTALL.in gendoc.combined.sed + rm -f $@ + for input in $^; do \ + case $$input in *.in) \ + sed -f gendoc.combined.sed $$input | nroff >> $@ ;; \ + esac; \ + done + echo '$$Document: $@ $$: end of file' >> $@ + rm -f gendoc.combined.sed + # Workspace clean-up... # clean: rm -f *.$(OBJEXT) *.d *.dll $(BIN_PROGRAMS) $(LIBEXEC_PROGRAMS) distclean: clean - rm -f config.* version.c Makefile + rm -f config.* version.c maintainer-clean: distclean - rm -f pkginfo.c *-$(PACKAGE_DISTVERSION)-*.tar.gz - rm -rf ${PACKAGE_DISTROOT} staged + rm -f README NEWS INSTALL readme.txt Makefile pkginfo.c + rm -f *-$(PACKAGE_DISTVERSION)-*.tar.gz *-$(PACKAGE_DISTVERSION)-*.zip + rm -rf ${PACKAGE_DISTROOT} staged ${srcdir}/autom4te.cache # $RCSfile$: end of file diff --git a/README b/README deleted file mode 100644 index 6c14bb0..0000000 --- a/README +++ /dev/null @@ -1,351 +0,0 @@ -Release Notes for mingw-get-0.1-mingw32-alpha-5 - -$Id$ - -Preamble --------- - -This is the fifth alpha release of mingw-get; this is primarily a bug -fix release, with few user visible changes. The installation procedure -remains the same as for previous releases. To upgrade from a previous -release, simply run - - mingw-get update - mingw-get upgrade mingw-get - -or alternatively, unpack the -bin package over the top of the existing -installation. For further information, and usage advice, see: - - http://mingw.org/wiki/Getting_Started - - -User Visible Changes for mingw-get-0.1-mingw32-alpha-5 ------------------------------------------------------- - -- Improved self-upgrade support; it incorporates a work around to avoid - a potential race condition in mingw-get-inst; (c.f. MinGW bug 3075616); - mingw-get.exe and mingw-get-0.dll are renamed, (to move them out of the - way), only when performing an explicit upgrade of the mingw-get-bin - package itself. - -- The follow-up release, designated as mingw-get-0.1-mingw32-alpha-5.1, - is a bug-fix release to correct a critical defect in the resolution of - dependencies, when performing an upgrade operation. It also provides - more meaningful diagnostics when mingw-get is invoked without arguments, - and corrects some omissions from the source tarball. - -- The follow-up release, designated as mingw-get-0.1-mingw32-alpha-5.2, - is a further bug-fix release. It provides a work-around for a defect - in the console I/O handling of MSYS mintty and MSYS rxvt, which causes - the stderr stream to appear to be inappropriately buffered within either - of these terminal emulators. As such, it is a recommended upgrade for - users of either of these emulators; it offers no tangible benefit to - other users. - - -=============================================== - - -Release Notes for mingw-get-0.1-mingw32-alpha-4 - -Preamble --------- - -This is the fourth alpha release of mingw-get; this is primarily a bug -fix release, with few user visible changes. The installation procedure -remains the same as for previous releases; to upgrade from a previous -release, simply unpack the -bin package over the top of the existing -installation. For further information, and usage advice, see: - - http://mingw.org/wiki/Getting_Started - - -User Visible Changes for mingw-get-0.1-mingw32-alpha-4 ------------------------------------------------------- - -- This release of mingw-get fixes a bug in the earlier self-upgrade - functionality, where any runtime error "deleted" mingw-get. (mingw-get - and its support file(s) were actually only renamed, but recovery was - difficult). Now, "ordinary" errors such as bad command line arguments, - failed downloads, missing manifests, etc, will not cause this behavior. - However, a catastrophic operating system error may prevent the new - auto-recovery code from executing, leaving mingw-get in its "deleted" - (e.g. renamed) state. If this occurs, simply do the following: - - cd /mingw - mv bin/mingw-get.exe~ bin/mingw-get.exe - mv libexec/mingw-get/mingw-get-0.dll~ libexec/mingw-get/mingw-get-0.dll - -- Add --help|-h option - - -=============================================== - - -Release Notes for mingw-get-0.1-mingw32-alpha-3 - -Preamble --------- - -This is the third alpha release of mingw-get; this is primarily a bug -fix release, with few user visible changes. The installation procedure -remains the same as for previous releases; to upgrade from a previous -release, simply unpack the -bin package over the top of the existing -installation. For further information, and usage advice, see: - - http://mingw.org/wiki/Getting_Started - - -User Visible Changes for mingw-get-0.1-mingw32-alpha-3 ------------------------------------------------------- - -- There is no profile.xml file shipped with this release; users who - are installing for the first time are advised to copy the supplied - var/lib/mingw-get/data/defaults.xml configuration file prototype to - var/lib/mingw-get/data/profile.xml, which may then be customised as - required; (if no customisation is required, mingw-get can use the - defaults.xml file directly, but will warn that profile.xml does - not exist). - -- Within defaults.xml, the %R macro has been formally adopted as the - mechanism for specifying the installation paths for both MinGW and - for MSYS; this binds the default installation paths for both MinGW - and MSYS to the installation directory of mingw-get itself, since - the absolute path to mingw-get.exe is identified as: - - %R\bin\mingw-get.exe - - with default base directory paths being defined for each of MinGW - and MSYS respectively as: - - %R\ - %R\msys\1.0\ - - This arrangement makes it possible for users to choose installation - locations for both MinGW and MSYS, simply by making the choice of - where to install mingw-get, without any further need to create, or - to modify profile.xml, (although, to avoid warnings about a missing - profile.xml, users may prefer to copy or rename defaults.xml). As - for previous releases, the recommended directory for installation is - C:\MinGW\, and this should not be changed without pressing reason; in - any event, users who insist on changing it should be aware that, if - they choose any installation directory which includes white space in - its absolute path name, their installation may not work correctly, - and such installations will not be supported by the MinGW Project. - -- This release of mingw-get incorporates necessary infrastructure to - support future upgrades to itself, using its own internal upgrade - facility. This is the first release to support this capability; - however, the effect will not become apparent until upgrading to - the next release. - - -=============================================== - - -Release Notes for mingw-get-0.1-mingw32-alpha-2 - -Preamble --------- - -This is the second alpha release of mingw-get. The majority of changes -since the first alpha release are developer centric, with little end -user impact. Thus, users are advised to review the release notes for -mingw-get-0.1-mingw32-alpha-1, (appended below); the procedure for the -installation and usage of the alpha-2 release is similar to that for -alpha-1, with a few minor user-visible changes. - - -User Visible Changes for mingw-get-0.1-mingw32-alpha-2 ------------------------------------------------------- - -- The var/lib/mingw-get/data/profile.xml file is no longer included in - the distribution tarball, (or zipfile); instead, a prototype for this - file is provided as var/lib/mingw-get/data/defaults.xml - -- The repository section of profile.xml may now omit any specific - reference to a named package-list catalogue, allowing mingw-get to - interrogate a default catalogue on the repository host. Users who - have previously installed a modified profile.xml are advised to - incorporate changes to the repository definition from defaults.xml - into their profile.xml - -- Users who do not wish to provide a customised profile.xml are advised - to copy or rename the provided defaults.xml file to profile.xml; this - remains the preferred name for the configuration file, and mingw-get - will look for it first. If it cannot be found, mingw-get will issue - a warning, before looking for defaults.xml as an alternative. - -- The structure of the repository catalogue has changed, to more readily - accommodate dynamic incremental distribution updates, without requiring - a corresponding update to mingw-get itself. While this affects package - maintainers more than end users, such users are advised to perform a - regular `mingw-get update', at intervals of a few weeks, to capture - catalogue updates. - -- As a consequence of the preceding change, the list of packages known - to mingw-get is no longer restricted, as it was previously; additional - or more up-to-date packages may become available from time to time, as - individual package maintainers add the appropriate manifests to the - online repository catalogue; use `mingw-get update' to capture such - new and updated packages. - -At the time of this release, the packages recorded in the distribution -manifest remain as for the alpha-1 release. With the improved handling -of manifests, additional (and more up-to-date) packages will be added -soon after this release, and will become immediately available to users, -on running `mingw-get update'. - - -=============================================== - - -Release Notes for mingw-get-0.1-mingw32-alpha-1 - -Preamble --------- - -This is the first alpha release of the next generation MinGW installer, -mingw-get; it provides a more readily extensible, and more configurable -alternative to the existing MinGW-5.1.x series of NSIS installers, for -installing MinGW packages. - -mingw-get is free software. Permission is granted to copy, modify and -redistribute it, under the provisions of the GNU General Public License, -Version 3, (or, at your option, any later version), as published by the -Free Software Foundation; see the file COPYING for licensing details. - -Note, in particular, that mingw-get is provided "as is", in the hope -that it may prove useful, but WITHOUT WARRANTY OF ANY KIND; not even an -implied WARRANTY OF MERCHANTABILITY, nor of FITNESS FOR ANY PARTICULAR -PURPOSE. Under no circumstances will the authors, or the MinGW Project, -accept liability for any damages, however caused, arising from the use -of this software. - -At the time of this release, mingw-get is still in the early stages of -development; this release provides an opportunity for early adopters to -evaluate the CLI capabilities of the installer component; please report -bugs, (but please, not the known issues identified below), to the MinGW -bug tracker: http://sourceforge.net/tracker/?group_id=2435&atid=102435 - - -Installation ------------- - -To install mingw-get, visit the MinGW files repository at: - - http://sourceforge.net/projects/mingw/files - -and, from the "Automated MinGW Installer/mingw-get" folder, download -your choice of either: - - mingw-get-0.1-mingw32-alpha-1-bin.zip - -or: - - mingw-get-0.1-mingw32-alpha-1-bin.tar.gz - -and unpack it into the directory in which you intend to host your MinGW -installation, (the standard default of C:\MinGW [*] is recommended), then -use your preferred method for assignment of environmet variables to add -the appropriate directory, (default C:\MinGW\bin), to your PATH. - -[*] If you insist on adopting a different directory from the recommended -default, you are *strongly* recommended to avoid any directory which has -white space in its absolute path name; in particular, those who choose to -ignore this advice, and install MinGW within "C:\Program Files", usually -discover, to their cost, that certain tools do not work correctly. - - -Configuration -------------- - -If you have installed mingw-get in the default location, you will find -its primary configuration file at: - - C:\MinGW\var\lib\mingw-get\data\profile.xml - -(if you chose a different location, replace "C:\MinGW" with your chosen -installation prefix directory path name). - -This is a liberally commented XML file, which you are free to modify as -you see fit, to suit your own installation requirements. At the present -time, the only entries you should consider changing are the path names -specified by the "path" attribute associated with each of the "sysroot" -elements within the first (only) "system-map" element. (These specify -the prefix directory path names for your installation; you probably want -to make the path for the "mingw32" subsystem to match your choice for -your mingw-get installation, if you chose not to adopt the default, in -which case you will probably also prefer an alternative choice for the -MSYS subsystem, if you intend to install that). - -If you do choose to modify the configuration, you are advised to keep a -backup copy of your modified version, since, particularly during the -alpha phase of development, it may be necessary to overwrite your local -version with an updated distributed version, then fold in your changes -once more. - - -Invocation ----------- - -Invoking mingw-get from the command line, without arguments, is intended -to launch a GUI variant of the application, (but currently, this mode is -not supported; if you try it, you *will* see only an error message). - -To invoke the CLI variant of mingw-get, the syntax is: - - mingw-get [-option ...] action [package ...] - -Currently supported options are: - - -version display the version banner, and exit - -Currently supported actions are: - - update synchronise the locally cached version - of the distribution manifest with the - version held at the repository. - - install package ... install the specified package(s), and - any necessary prerequisites. - - upgrade package ... upgrade package(s) from the installed - version to the newest version available, - (if not already at the newest version). - - remove package ... uninstall package(s). - -Currently known packages are: - - mingwrt the mingw32 runtime libraries. - w32api the MS-Windows API bindings for mingw32. - binutils the GNU binary file utilities. - gcc the GNU C Compiler (currently v3.4.5) - g++ the C++ front-end for GCC-3.4.5 - g77 the FORTRAN-77 front-end for GCC-3.4.5 - ada the Ada front-end for GCC-3.4.5 - java the java front-end for GCC-3.4.5 - objc the Objective-C front-end for GCC-3.4.5 - mingw32-make native MS-Win32 build of GNU make. - - -Known Issues ------------- - -Please do not file bug reports, in respect of the following issues: - -1) Cannot start in GUI mode; the error message you see, when you try, is - expected behaviour, in current alpha releases. - -2) "remove" action does not uninstall anything; the uninstaller function - is currently a stub, so this is expected behaviour. - -3) Package list needs updating, for more recent releases; we hope to - address this progressively, in coming weeks. Please check the online - release notes/announcements, and run "mingw-get update" periodically. - -4) Need an action to list available/installed packages. - -5) Additional features you would like to see added; we want to know your - ideas, but please raise them for discussion on the mailing-list first. diff --git a/src/clistub.c b/src/clistub.c index e818551..d7cd439 100644 --- a/src/clistub.c +++ b/src/clistub.c @@ -155,21 +155,26 @@ wchar_t *AppPathNameW( const wchar_t *relpath ) extern const char *version_identification; static const char *help_text = -"mingw-get [OPTIONS] ACTION package-spec [package-spec ...]\n" -"Manage MinGW and MSYS installations (Command-line user interface).\n\n" +"Manage MinGW and MSYS installations (command line user interface).\n\n" +"Usage:\n" +" mingw-get [OPTIONS] ACTION [package-spec ...]\n\n" +" mingw-get update\n" +" mingw-get [OPTIONS] {install | upgrade | remove} package-spec ...\n" +" mingw-get [OPTIONS] {show | list} [package-spec ...]\n\n" "Options:\n" " --help, -h Show this help text\n" " --version, -V Show version and licence information\n\n" "Actions:\n" " update Update local copy of repository catalogues\n" +" list, show List and show details of available packages\n" " install Install new packages\n" -" remove [not implemented] Remove previously installed packages\n" -" upgrade [not implemented] Upgrade previously installed packages\n\n" +" upgrade Upgrade previously installed packages\n" +" remove Remove previously installed packages\n\n" "Package Specifications:\n" -" [subsystem]-name-[component]:\n" +" [subsystem-]name[-component]:\n" " msys-bash-doc The 'doc' component of the bash package for MSYS\n" -" mingw32-gdb All components of the gdb package for MinGW\n" -"See /mingw/var/lib/mingw-get/data/*.xml for possible package names\n" +" mingw32-gdb All components of the gdb package for MinGW\n\n" +"Use 'mingw-get list' to identify possible package names\n" "and the components associated with each.\n\n"; #define IMPLEMENT_INITIATION_RITES PHASE_ONE_RITES diff --git a/srcdist-doc/INSTALL.in b/srcdist-doc/INSTALL.in new file mode 100644 index 0000000..8b129d7 --- /dev/null +++ b/srcdist-doc/INSTALL.in @@ -0,0 +1,295 @@ +Installation Instructions +========================= + +$Id$ + +The information which follows describes the procedure for installing +and configuring mingw-get, and for keeping the installation current. +The online version of this document is an abridged form, focussing on +the installation of binary releases; users who prefer to build and +install from source are advised to consult the unabridged form of +this document, which may be found in the file "INSTALL", within the +source code distribution tarball. + +Please report bugs as directed at http://mingw.org/Reporting_Bugs + + +First Time Installation of a Binary Release +------------------------------------------- + +To install mingw-get, visit the MinGW files repository at: + + http://sourceforge.net/projects/mingw/files + +and, from the "Automated MinGW Installer/mingw-get" folder, +download your choice of either: + + {PACKAGE_DISTNAME}-bin.zip + +or (preferred, if you know how to unpack it): + + {PACKAGE_DISTNAME}-bin.tar.gz + +Whichever of these you choose to download, you should unpack it into +the directory in which you intend to host your MinGW installation; (we +*strongly* recommend that you adopt our standard of C:\MinGW [*], unless +you have an exceptional reason to make an alternative choice), then use +your preferred method for assignment of environment variables to add the +appropriate directory (default C:\MinGW\bin) to your PATH; (this should +be added as a permanent PATH assignment). + +Having completed this phase of installation, you may then wish to review +the following section on configuration; if nothing else, you may wish to +copy the supplied defaults.xml file to profile.xml, even if you choose not +to introduce any customisations. Finally, to initialise the installation +recording database, you should run the command [**]: + + C:\> mingw-get install mingw-get + + +[*] If you insist on adopting a different directory from the recommended +default, you are *strongly* advised to avoid any directory which has white +space in its absolute path name; in particular, those who choose to ignore +this advice, and install MinGW into some subdirectory of (for example) +C:\Program Files", usually discover to their cost that certain +tools may not work correctly. + +This document will refer to files as though installed in the recommended +default location, with a path prefix of C:\MinGW. If, having read the +above warning, you do decide to adopt an alternative installation path, +then please substitute your alternative prefix, as appropriate, where this +document refers to C:\MinGW. + +[**] If you have chosen {PACKAGE_DISTNAME}-bin.tar.gz as your installation +source, rather than {PACKAGE_DISTNAME}-bin.zip, you may like to create the +directory: + + C:\MinGW\var\cache\mingw-get\packages + +(together with any requisite parents, and adjusting the C:\MinGW prefix +to suit your installation choice, if necessary). You may then move the +{PACKAGE_DISTNAME}-bin.tar.gz file to it, *before* you run the above +command; this will relieve mingw-get of the overhead which would be +incurred by downloading the file a second time. + + +Specifying the Configuration +---------------------------- + +When you invoke mingw-get, it will attempt to read configuration data +from the file: + + C:\MinGW\var\lib\mingw-get\data\profile.xml + +(with any necessary adjustment of the C:\MinGW installation prefix, as +noted previously); if, and only if, this file cannot be read, then a +fallback attempt will be made, to read the configuration from: + + C:\MinGW\var\lib\mingw-get\data\defaults.xml + +instead. Of this pair of files, profile.xml is *not* included within +the mingw-get distribution, but defaults.xml *is*. It is a liberally +commented XML file, which you are advised to copy to create profile.xml; +you may then modify this, as you see fit, to suit your own installation +requirements. [*] + +At the present time, the only entries you should consider changing are +the path names specified by the "path" attribute associated with each +of the "sysroot" elements within the first (only) "system-map" element; +(these specify the prefix directory path names for your installation). +You probably want to make the path for the "mingw32" subsystem match +your choice for your mingw-get installation; (the "%R" notation, used +in defaults.xml, sets it up thus, regardless of whether you choose to +install in C:\MinGW, or an alternative location). + +[*] The recommendation to copy defaults.xml to profile.xml may seem to +be an unnecessary inconvenience; it is implemented this way in order to +safeguard any configuration changes you wish to make; during an upgrade, +defaults.xml will be overwritten, but profile.xml will not, so your +configuration will be preserved. + + +Upgrading an Existing Installation to a Newer Binary Release +------------------------------------------------------------ + +Once you have completed a first-time installation of mingw-get, whether +from a binary release or by building and installing from source, you may +wish to upgrade it, as the project team publishes new releases. Unless +you insist on *always* installing from source, (in which case each +upgrade effectively becomes a fresh first-time installation from the +new source code), and provided: + +- you have previously installed mingw-get-0.1-mingw32-alpha-3 or newer, + and + +- you have completed the first-time installation process, by running + + C:\> mingw-get install mingw-get + +then you may upgrade to a newer binary release by running + +! C:\> mingw-get update +! C:\> mingw-get upgrade mingw-get + +Otherwise, if you have a previously unfinalised installation, i.e. you +did not previously run + + C:\> mingw-get install mingw-get + +and that previous installation is of mingw-get-0.1-mingw32-alpha-3 or +newer, then you may upgrade and finalise by running + +! C:\> mingw-get update +! C:\> mingw-get install mingw-get + +Alternatively, any previous installation of mingw-get may be upgraded +by simply performing a new first-time installation, overwriting the +previously installed version; (this is the only option available, if +the original installation predates mingw-get-0.1-mingw32-alpha-3). + +;--------8<-------------------- cut-line -------------------->8-------- +; +; Any text added below the cut-line will be included in the INSTALL +; file, which is to be included in the source distribution, but it +; will be excluded from the readme.txt file, which is to be used to +; add descriptive content on the SourceForge download page. +; +; Any lines, such as these, which begin with a semicolon in their +; first column (not indented), will be excluded from both files. +; + +Building and Installing from Source +----------------------------------- + +In order to build mingw-get from source, you will require: + +- A build platform which is capable of running Bourne shell scripts, + which provides at least the set of core tools required by the GNU + Coding Standards, together with a C/C++ compiler suite generating + code for execution on a native MS-Windows host. Suitable platforms + include MSYS, in it's normal MinGW personality, with the MinGW + compiler suite, or either of Cygwin or GNU/Linux, with a suitable + cross-compiler suite for a MinGW host. + +- A statically linkable libz.a (or equal) for the native MS-Windows + host, together with its associated header files. + +- A statically linkable libbz2.a (or equal) for the native MS-Windows + host, together with its associated header files. + +- A statically linkable liblzma.a (or equal) for the native MS-Windows + host, together with its associated header files; (this should be built + from libxz sources no older than version 4.999.9beta). + +Having provisioned a suitable build platform, with these pre-requisite +libraries installed, you should obtain and unpack the source tarball, +{PACKAGE_DISTNAME}-src.tar.gz, in any working directory of your choice, +to create your {PACKAGE_DIRNAME} source directory. + +At this point, you may elect to build in-source, in which case you would +follow the conventional GNU build procedure: + +! $ cd {PACKAGE_DIRNAME} +! $ ./configure --prefix=/mingw [options ...] +! $ make + +However, it is strongly recommended that you elect instead, to create +and use a separate build directory. This may be a subdirectory of your +{PACKAGE_DIRNAME} source directory, e.g. build-dir, in which case +you would proceed as follows: + +! $ mkdir {PACKAGE_DIRNAME}/build-dir +! $ cd {PACKAGE_DIRNAME}/build-dir +! $ ../configure --prefix=/mingw [options ...] +! $ make + +Finally, if you are building on the host on which you intend to deploy, +and provided the build has completed without error, you may install +mingw-get by executing: + +! $ make install + +or: + +! $ make install-strip + +Alternatively, if you wish to create an installation kit for deployment +on any remote host, you may: + +! $ mkdir staged +! $ make prefix=`pwd`/staged install + +or: + +! $ mkdir staged +! $ make prefix=`pwd`/staged install-strip + +and then: + +! $ cd staged +! $ tar cf ../{PACKAGE_DISTNAME}-inst.tar . + +to create an installation tarball, which may be deployed simply by +unpacking it in the /mingw root directory, on any host you choose. + + +Building and Installing from Source in CVS +------------------------------------------ + +If, rather than building mingw-get from the source code provided in the +form of a release tarball, you prefer to keep on the cutting edge of +development within the public CVS repository, there are a few additional +pre-requisites which you must satisfy on your build platform: + +- You must have a CVS client, which you can use to fetch the source code + from the repository, and subsequently keep it current. + +- You must have the GNU autoconf package, with a version number of 2.59 + or later, (and preferrably 2.67 or later). + +- You must have a working lex, (or flex), scanner generating tool. + +- If you also wish to be able to generate the documentation files, as + included in the top level directory of a source distribution tarball, + you will need a working nroff implementation. + +Provided you can satisfy (at least the first three of) these additional +pre-requisites, you may check out the latest source code thus [*]: + +! $ export CVSROOT +! $ CVSROOT=:pserver:anonymous@mingw.cvs.sf.net:/cvsroot/mingw +! $ cvs login +! $ cvs -z3 co -P mingw-get + +This will create a working copy of the mingw-get source tree, in the +mingw-get subdirectory of your current working directory. + +[*] If you are an accredited MinGW Developer, you may prefer to use the +:ext: access protocol of CVS, in conjunction with your registered SSH +keys, to access the CVS repository; in this case, you should know the +appropriate procedure to use, in place of the above. + +Having thus obtained your working copy of the source code from the CVS +repository, you should then: + +! $ cd mingw-get +! $ autoconf + +to generate the configure script, and then: + +! $ mkdir obj +! $ cd obj +! $ ../configure --prefix=/mingw [options ...] +! $ make + +to progress the build [**], as in the previous case of building from the +source code extracted from a distribution tarball. + +[**] Notice that here we choose to build in a subdirectory called obj; +when building from source in CVS, building in-source becomes even less +desirable than it is when building from distributed source. The choice +of obj for the build directory name is dictated by the configuration of +mingw-get's CVS module itself; cvs "knows" that this directory does not +contain any source files of interest to it. + +$RCSfile$: end of file diff --git a/srcdist-doc/NEWS.in b/srcdist-doc/NEWS.in new file mode 100644 index 0000000..4dabcf7 --- /dev/null +++ b/srcdist-doc/NEWS.in @@ -0,0 +1,227 @@ +Release Notes +============= + +$Id$ + +The information presented below describes the user visible changes +introduced with each release of mingw-get. + + +mingw-get-0.2-mingw32-alpha-1 +----------------------------- + +Release date: 2011-??-?? + +- Added provisional support for removal of packages which have been + previously installed. This is fully functional, but naive with respect + to dependencies; it will aggressively remove any package scheduled for + removal, even if this may break another (dependant) package. + + A future release will address this naivety, performing more rigorous + dependency checking prior to progressing removals. Meanwhile, should it + be discovered that removal of a package has broken any dependency, then + reinstallation of the dependant package should correct the situation. + +- The upgrade operation now performs a removal of the currently installed + version of each package, prior to installing a replacement; this ensures + that obsolete artifacts from earlier versions do no accumulate within + the file system. + + As with the remove operation, this implementation does not check that an + upgrade is compatible with dependant packages; this will be addressed in + a future release. + +- Added preliminary support for the "list" operation. This provides a + rudimentary mechanism for interrogating the package catalogue, and + displaying a list of available packages. + +- Added preliminary support for the "show" operation. As currently + implemented, this behaves as a synonym for "list"; as functionality + develops, the behaviours of these two operators may become distinct in + future releases. + + +mingw-get-0.1-mingw32-alpha-5.2 +------------------------------- + +Release date: 2011-02-26 + +- This is a further bug-fix release. It provides a work-around for a + defect in the console I/O handling of MSYS mintty and MSYS rxvt, which + causes the stderr stream to appear to be inappropriately buffered within + either of these terminal emulators. As such, it is a recommended upgrade + for users of either of these emulators; it offers no tangible benefit + to other users. + + +mingw-get-0.1-mingw32-alpha-5.1 +------------------------------- + +Release date: 2011-02-10 + +- This is a bug-fix release to correct a critical defect in the resolution + of dependencies, when performing an upgrade operation. It also provides + more meaningful diagnostics when mingw-get is invoked without arguments, + and corrects some omissions from the source tarball. + + +mingw-get-0.1-mingw32-alpha-5 +----------------------------- + +Release date: 2010-10-29 + +- Improved self-upgrade support; it incorporates a work around to avoid + a potential race condition in mingw-get-inst; (c.f. MinGW bug 3075616); + mingw-get.exe and mingw-get-0.dll are renamed, (to move them out of the + way), only when performing an explicit upgrade of the mingw-get-bin + package itself. + + +mingw-get-0.1-mingw32-alpha-4 +----------------------------- + +Release date: 2010-09-10 + +- Fixes a bug in the earlier self-upgrade + functionality, where any runtime error "deleted" mingw-get. (mingw-get + and its support file(s) were actually only renamed, but recovery was + difficult). Now, "ordinary" errors such as bad command line arguments, + failed downloads, missing manifests, etc, will not cause this behavior. + However, a catastrophic operating system error may prevent the new + auto-recovery code from executing, leaving mingw-get in its "deleted" + (e.g. renamed) state. If this occurs, simply do the following: + +; The initial exclamation marks, here, introduce a preformatted block +; with absolute indentation; each is replaced by a space, on output. +; (These comment lines -- with initial semicolon -- are not copied to +; the formatted output stream). +; +! $ cd /mingw +! $ mv bin/mingw-get.exe~ bin/mingw-get.exe +! $ mv libexec/mingw-get/mingw-get-0.dll~ \ +! libexec/mingw-get/mingw-get-0.dll + +- Add --help|-h option + + +mingw-get-0.1-mingw32-alpha-3 +----------------------------- + +Release date: 2010-08-30 + +- There is no profile.xml file shipped with this release; users who + are installing for the first time are advised to copy the supplied + var/lib/mingw-get/data/defaults.xml configuration file prototype to + var/lib/mingw-get/data/profile.xml, which may then be customised as + required; (if no customisation is required, mingw-get can use the + defaults.xml file directly, but will warn that profile.xml does + not exist). + +- Within defaults.xml, the %R macro has been formally adopted as the + mechanism for specifying the installation paths for both MinGW and + for MSYS; this binds the default installation paths for both MinGW + and MSYS to the installation directory of mingw-get itself, since + the absolute path to mingw-get.exe is identified as: + + %R\bin\mingw-get.exe + + with default base directory paths being defined for each of MinGW + and MSYS respectively as: + +; The initial exclamation marks, here, introduce a preformatted block +; with absolute indentation; each is replaced by a space, on output. +; (These comment lines -- with initial semicolon -- are not copied to +; the formatted output stream). +; +! %R\ +! %R\msys\1.0\ + + This arrangement makes it possible for users to choose installation + locations for both MinGW and MSYS, simply by making the choice of + where to install mingw-get, without any further need to create, or + to modify profile.xml, (although, to avoid warnings about a missing + profile.xml, users may prefer to copy or rename defaults.xml). As + for previous releases, the recommended directory for installation is + C:\MinGW\, and this should not be changed without pressing reason; in + any event, users who insist on changing it should be aware that, if + they choose any installation directory which includes white space in + its absolute path name, their installation may not work correctly, + and such installations will not be supported by the MinGW Project. + +- This release of mingw-get incorporates necessary infrastructure to + support future upgrades to itself, using its own internal upgrade + facility. This is the first release to support this capability; + however, the effect will not become apparent until upgrading to + the next release. + + +mingw-get-0.1-mingw32-alpha-2 +----------------------------- + +Release date: 2010-05-17 + +- The var/lib/mingw-get/data/profile.xml file is no longer included in + the distribution tarball, (or zipfile); instead, a prototype for this + file is provided as var/lib/mingw-get/data/defaults.xml + +- The repository section of profile.xml may now omit any specific + reference to a named package-list catalogue, allowing mingw-get to + interrogate a default catalogue on the repository host. Users who + have previously installed a modified profile.xml are advised to + incorporate changes to the repository definition from defaults.xml + into their profile.xml + +- Users who do not wish to provide a customised profile.xml are advised + to copy or rename the provided defaults.xml file to profile.xml; this + remains the preferred name for the configuration file, and mingw-get + will look for it first. If it cannot be found, mingw-get will issue + a warning, before looking for defaults.xml as an alternative. + +- The structure of the repository catalogue has changed, to more readily + accommodate dynamic incremental distribution updates, without requiring + a corresponding update to mingw-get itself. While this affects package + maintainers more than end users, such users are advised to perform a + regular `mingw-get update', at intervals of a few weeks, to capture + catalogue updates. + +- As a consequence of the preceding change, the list of packages known + to mingw-get is no longer restricted, as it was previously; additional + or more up-to-date packages may become available from time to time, as + individual package maintainers add the appropriate manifests to the + online repository catalogue; use `mingw-get update' to capture such + new and updated packages. + +At the time of this release, the packages recorded in the distribution +manifest remain as for the alpha-1 release. With the improved handling +of manifests, additional (and more up-to-date) packages will be added +soon after this release, and will become immediately available to users, +on running `mingw-get update'. + + +mingw-get-0.1-mingw32-alpha-1 +----------------------------- + +Release date: 2010-02-16 + +This is the first alpha release of the next generation MinGW installer, +mingw-get; it provides a more readily extensible, and more configurable +alternative to the existing MinGW-5.1.x series of NSIS installers, for +installing MinGW packages. + +At the time of this release, mingw-get is still in the early stages of +development; this release provides an opportunity for early adopters to +evaluate the CLI capabilities of the installer component; please report +bugs, (but please, not the known issues identified below), to the MinGW +bug tracker: http://sourceforge.net/tracker/?group_id=2435&atid=102435 + +;--------8<-------------------- cut-line -------------------->8-------- +; +; Any text added below the cut-line will be included in the README +; file, which is to be included in the source distribution, but it +; will be excluded from the readme.txt file, which is to be used to +; add descriptive content on the SourceForge download page. +; +; Any lines, such as these, which begin with a semicolon in their +; first column (not indented), will be excluded from both files. +; +$RCSfile$: end of file diff --git a/srcdist-doc/README.in b/srcdist-doc/README.in new file mode 100644 index 0000000..71f21d9 --- /dev/null +++ b/srcdist-doc/README.in @@ -0,0 +1,67 @@ +MinGW Package Download and Installation Tool +============================================ + +$Id$ + +Description +----------- + +mingw-get is a tool to assist users in the management of MinGW and MSYS +software installations. Configured via an online XML database, which is +managed by the project maintainers, it offers a command line driven user +interface facilitating selective download and installation of packages +provided by the project. + +The XML database provides maintainers with a mechanism for the +specification of inter-package dependencies; this permits configuration +of any package, such that the end user may elect to install just that +specific package, leaving mingw-get to ensure that all dependencies will +be automatically satisfied at installation time. + +A graphical user interface is planned as a future enhancement. + + +Licensing Terms +--------------- + +mingw-get is free software. +Permission is granted to copy, modify and redistribute this +software, under the provisions of the GNU General Public License, +Version 3, (or, at your option, any later version), as published by +the Free Software Foundation; see the file COPYING, which is +distributed with the mingw-get-lic package, and with the source +code, for licensing details. + +Note, in particular, that mingw-get is provided "as is", in the +hope that it may prove useful, but WITHOUT WARRANTY OF ANY KIND; not +even an implied WARRANTY OF MERCHANTABILITY, nor of FITNESS FOR ANY +PARTICULAR PURPOSE. Under no circumstances will the author, or the +MinGW Project, accept liability for any damages, however caused, +arising from the use of this software. + +;--------8<-------------------- cut-line -------------------->8-------- +; +; Any text added below the cut-line will be included in the README +; file, which is to be included in the source distribution, but it +; will be excluded from the readme.txt file, which is to be used to +; add descriptive content on the SourceForge download page. +; +; Any lines, such as these, which begin with a semicolon in their +; first column (not indented), will be excluded from both files. +; + +Further Information +------------------- + +For development history, and details of features included in successive +releases of mingw-get, please refer to the NEWS file. + +For installation and configuration instructions, see the file INSTALL. + + +Reporting Bugs +-------------- + +Please file bug reports as directed at http://mingw.org/Reporting_Bugs + +$RCSfile$: end of file diff --git a/srcdist-doc/gendoc.sed.in b/srcdist-doc/gendoc.sed.in new file mode 100644 index 0000000..c2f4446 --- /dev/null +++ b/srcdist-doc/gendoc.sed.in @@ -0,0 +1,106 @@ +# gendoc.in -- vim:filetype=nroff +# +# $Id$ +# +s/{PACKAGE_DISTNAME}/${PACKAGE_DISTNAME}/g +# +# Written by Keith Marshall +# Copyright (C) 2011, MinGW Project +# +# +# Sed script to prepare README, NEWS and INSTALL distributable files +# for formatting using nroff. +# +# +# This is free software. Permission is granted to copy, modify and +# redistribute this software, under the provisions of the GNU General +# Public License, Version 3, (or, at your option, any later version), +# as published by the Free Software Foundation; see the file COPYING +# for licensing details. +# +# Note, in particular, that this software is provided "as is", in the +# hope that it may prove useful, but WITHOUT WARRANTY OF ANY KIND; not +# even an implied WARRANTY OF MERCHANTABILITY, nor of FITNESS FOR ANY +# PARTICULAR PURPOSE. Under no circumstances will the author, or the +# MinGW Project, accept liability for any damages, however caused, +# arising from the use of this software. + + +# Add nroff set-up boilerplate, at the head of the input stream. +# +1i \ +.pl 1 \ +.ll 72 \ +.hy 0 + +# Identify the top level directory name in a source distribution. +# +s/{PACKAGE_DIRNAME}/${PACKAGE_DIRNAME}/g + +# Each source file is permitted to include one or more cut-lines; +# (only the first is significant). Any text included after the +# first such line is discarded, when compiling a composite output +# file. (We MUST do this BEFORE stripping comments, since the +# cut-line itself may most likely be flagged as a comment). +# +# cut:/--8<--/,$d +# cut:/$Id[$:]/{ +# cut: s/README.in,v/readme.txt/; t; N; d +# cut:} + +# Strip comment lines; (i.e. those with semi-colon at left margin). +# +/^;/d + +# Ensure that underlining for headings and sub-headings is placed on +# a new line, below the text of the heading. +# +/^[-=]\{2,\}/i \ +.br + +# When the author types a backslash, assume that his intent is for +# it to appear literally in the formatted output; this means that +# we must escape it, when input to nroff. +# +s/\\/\\\\/g + +# Since we've just made backslashes represent themselves, literally, +# we need a mechanism for introducing some nroff special characters; +# for this, we interpret certain XML entity codes. +# +s/ /\\ /g + +# Handle indented blocks, with a pseudo-bullet and hanging indent +# on the first line. +# +/^[-+*] */,/^[ ]*$/{ + /^\(- *\)/{ + h; s/^\([-+*]\)\( *\).*/.in \\w'\1\2'u\n.ti 0/ + x; s/^\([-+*]\)\( *\)/\\Z'-'\\h!\\w'\1\2'u!/; H; g + } + s/^ *// + s/^[ ]*$/\n.in 0/ +} + +# Handle indented blocks, keeping the indentation uniform. +# +/^ */,/^[ ]*$/{ + /^\( *\)/{ + h; s/^\( *\).*/'in \\w'\1'u/; x + s/^ *//; H; g + } + s/^[ ]*$/\n.in 0/ +} + +# To make indented lines explicitly unfilled, we introduce them with +# an exclamation mark in column 1, followed by at least one space. +# +s/^! / / + +# Footnotes are introduced by one or more asterisks enclosed in square +# brackets, and followed by one or more spaces; we want to protect the +# initial space from possible adjustment. +# +s/^\(\[\*\**] *\)/\\Z'\1'\\h!\\w'\1'u!/ + +# $RCSfile$: end of file -- 2.11.0