You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@corinthia.apache.org by ja...@apache.org on 2015/02/13 09:21:35 UTC
[06/33] incubator-corinthia git commit: Completed External
Downloading Description
Completed External Downloading Description
Additional description files are provided to guide the running and the
maintenance of the Windows procedures.
Project: http://git-wip-us.apache.org/repos/asf/incubator-corinthia/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-corinthia/commit/2d963742
Tree: http://git-wip-us.apache.org/repos/asf/incubator-corinthia/tree/2d963742
Diff: http://git-wip-us.apache.org/repos/asf/incubator-corinthia/diff/2d963742
Branch: refs/heads/experiment64
Commit: 2d963742473b25462502b491a1bd67d6b2097f66
Parents: 40fb232
Author: Dennis Hamilton <or...@apache.org>
Authored: Thu Jan 8 19:23:32 2015 -0800
Committer: Dennis Hamilton <or...@apache.org>
Committed: Thu Jan 8 19:23:32 2015 -0800
----------------------------------------------------------------------
external/README.txt | 117 +++++++++++++++++++------
external/customize.txt | 110 ++++++++++++++++++++++++
external/external.txt | 76 +++++++++++++++++
external/extract_downloads.bat | 16 ++--
external/fetch_downloads.bat | 15 ++--
external/maintenance.txt | 166 ++++++++++++++++++++++++++++++++++++
6 files changed, 461 insertions(+), 39 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-corinthia/blob/2d963742/external/README.txt
----------------------------------------------------------------------
diff --git a/external/README.txt b/external/README.txt
index 2dc9a6b..efbbfb4 100644
--- a/external/README.txt
+++ b/external/README.txt
@@ -1,24 +1,24 @@
-README.txt 1.0 UTF-8
+README.txt 1.1.0 UTF-8
- EXTERNAL DOWNLOADS AREA STRUCTURE
- =================================
+ EXTERNAL DOWNLOADS SETUP AND USE
+ ================================
The Corinthia repository external/ area is a section of the repository used
for downloading external dependencies required in constructing Corinthia code.
These dependencies are required when constructing Corinthia components on and
for Microsoft Windows.
-The downloads are created in an externals/download/ subdirectory. This is
+The downloads are created in an externals\download\ subdirectory. This is
not part of the repository and is created in a local working copy whenever
-needed. The scripts in externals/ provide the necessary downloading and
+needed. The scripts in externals\ provide the necessary downloading and
organization of the external material.
-The files directly in externals/ level provide documentation and scripts for
+The files directly in externals\ level provide documentation and scripts for
carrying out the download and extraction of material that Corinthia components
depend on for their compilation and executable operation. These files are
part of the Corinthia source code repository and are maintained with it.
-There are two uses for the externals/ source code,
+There are two uses for the externals\ source code,
1. as maintained scripts for downloading the current dependencies into
the download/ folder in a form that is used by build procedures where
@@ -29,6 +29,35 @@ There are two uses for the externals/ source code,
needed on Microsoft Windows.
+ CONTENT
+ 1. Prerequisites for Using the Scripts
+ 2. Operation
+ 3. Compile-Time Dependency on the External/Download Content
+ 4. External Files to be Included with Corinthia Software on Windows
+ 5. Maintenance and Customization Procedures
+ 6. Caveats
+
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
1. PREREQUISITES FOR USING THE SCRIPTS
-----------------------------------
@@ -40,72 +69,80 @@ operating system can be either x86 or x64 based.
The procedures employ Microsoft Windows batch (.bat) files and rely on the
Windows Scripting Host (WSH) for JScript access to Windows utility functions.
+The Windows Command Extensions must be in effect. (These are usually set by
+default and Visual Studio scripts depend on them also.)
-The scripts can be executed using a Windows Shell of the user's choice. They
+The scripts can be executed using a console shell of the user's choice. They
have been tested using Windows cmd.exe, Windows PowerShell, MSYS2 (bash),
CygWin (bash) and JSoft Take Command (formerly 4NT and 4DOS). They have been
-operated on Windows 8.1 Pro and Windows 10 Technical Preview as of January,
-2015.
+operated on Windows XP, Windows 8.1 Pro x64 and Windows 10 x64 Technical
+Preview as of January, 2015.
+
2. OPERATION
---------
In a console session, simply arrange to execute the script
- external/extract_downloads.bat
+ external\extract_downloads.bat
wherever it is located on the local system. The other script files are used
-as needed to complete the extraction operations.
+as needed to complete the extraction operations. The script will operate
+relative to its own location, not where it is executed from. That is,
+the downloads\ sub-folder is always created in the same folder that holds
+extract_downloads.bat and the other scripts.
-The external/download/ folder will be created if needed. Any external package
+The external\download\ folder will be created if needed. Any external package
that is not yet downloaded will be fetched from the Internet. Already-
downloaded packages will not be downloaded again. (To force a fresh set of
-downloads, simply delete the download/ subfolder.)
+downloads, simply delete the download\ subfolder.)
-The external packages will be stored in external/downloads/ and will remain
+The external packages will be stored in external\downloads\ and will remain
there for any future use so long as that folder is preserved.
If the set of external packages is complete, they will then be expanded into
-download/include/, download/lib/, and download/bin/ subdirectories with the
+download\include\, download\lib\, and download\bin\ subdirectories with the
files needed for compilation and execution of code that relies on the external
dependencies.
-This extraction is done completely whenever extract_downloads is operated. It
-will not be performed if not all of the package downloads have succeeded.
+This extraction is done completely each time extract_downloads is operated.
+Extraction is not performed if any of the package downloads are missing.
3. COMPILE-TIME DEPENDENCY ON THE EXTERNAL/DOWNLOAD CONTENT
--------------------------------------------------------
-The population of external/downloads/ is presumed in the root CMakeLists.txt
+The population of external\downloads\ is presumed in the root CMakeLists.txt
file in the 'if(${CMAKE_SYSTEM_NAME} MATCHES "Windows")' entry. That
definition and the current structure here must be kept synchronized.
-These externals are for builds targetted to Win32 x86 runtime only. Externals
+These externals are for builds targeted to Win32 x86 runtime only. Externals
needed for producing x64 executables require a different arrangement.
4. EXTERNAL FILES TO BE INCLUDED WITH CORINTHIA SOFTWARE ON WINDOWS
----------------------------------------------------------------
-The external/download/ folder is populated with include/, lib/, and bin/
+The external\download\ folder is populated with include\, lib\, and bin\
subfolders that carry extracted material that Corinthia code depends on when
compiled for Windows.
The compiled executables will need to be installed in folders that also have
-copies of DLLs from external/download/bin/
+copies of DLLs from external\download\bin\
- SDL2.dll
- SDL2_image.dll
iconv.dll
+ exit
libjpeg-9.dll
libpng16-16.dll
libtiff-5.dll
libwebp-4.dll
libxml2.dll
+ SDL2.dll
+ SDL2_image.dll
zlib1.dll
-The license files in bin/ should be carried along with those DLL files.
+The license files in bin\ are to be carried along with the DLL files they
+apply to.
Not every Corinthia component requires all of these DLLs. For finer details,
consult information on the individual component.
@@ -114,6 +151,34 @@ consult information on the individual component.
5. MAINTENANCE AND CUSTOMIZATION PROCEDURES
----------------------------------------
- [TBD]
+ The file maintenance.txt provides more information on how to perform
+ basic maintenance on these procedures.
+
+ The file customize.txt provides more information on adaptation of
+ the procedures for use in a differen location and download situation.
+
+ 6. CAVEATS
+ -------
+
+ The Windows Command Extensions must be enabled for the .bat scripts to
+ work properly.
+
+ The Windows file system is case insensitive. Any two file names and URLs
+ that differ only in case will collide. There are also more restrictions
+ on special characters. E.g., ":" may not be used in file names and "\"
+ is the path separator (not "/" which is also restricted).
+
+ The scripts can be unsuccessful without any failure indication. It is
+ necessary to use troubleshooting procedures to confirm that a download
+ is failing or that an extraction is not producing the expected content.
+ It is possible for a download to fail with a delivered but incorrect
+ file.
+
+
+REVISIONS
+
+ 1.1.0 2015-01-08-21:20 Updated Draft with complete coverage
+ 1.0.0 2015-01-08-15:21 Initial Draft replacement of the original README.txt
+
*** end of README.txt ***
http://git-wip-us.apache.org/repos/asf/incubator-corinthia/blob/2d963742/external/customize.txt
----------------------------------------------------------------------
diff --git a/external/customize.txt b/external/customize.txt
new file mode 100644
index 0000000..cb98e2f
--- /dev/null
+++ b/external/customize.txt
@@ -0,0 +1,110 @@
+customize.txt 1.0.0 UTF-8 2015-01-08
+
+ CUSTOMIZING EXTERNAL DOWNLOADS FOR OTHER DOWNLOADS
+ ==================================================
+
+ The external\ folder holds scripts and the download\ sub-folder for
+ external software that Corinthia Windows Win32 x86 builds depend on.
+
+ Note: This repository folder is intended to be usable when cloned to a
+ Microsoft platform. The notation for file paths reflects that, even
+ though POSIX path notation is used in the git and when viewed on GitHub.
+
+BASIC CUSTOMIZATION APPROACH
+
+The files, listed below, can be moved in their entirety to a new folder
+location where download of external materials is desired.
+
+The scripts are designed to operate relative to where they are stored. So
+if the scripts are moved to a folder named test-documents\, they will produce
+and populate a further sub-folder, either named download\ or a different name
+that is customized.
+
+One can make further modifications that deviate further from this structure.
+It is useful to make such changes in stages to ensure that the new organiza-
+tion is being honored correctly.
+
+Once the eight files are moved to their intended new home, customization at
+the detail is similar to following the maintenance procedure with allowance
+for the changes in location and desired operation.
+
+FILES TO MODIFY
+
+ .gitignore
+ Change the name of the download\ subfolder here if a different
+ folder outside of the managed source tree is used.
+
+ fetch_downloads.bat
+ The "download" name must be replaced everywhere that a different
+ folder name is to be used as the location of downloaded files. The
+ number of downloads and the names will also be changed by creation
+ of appropriate :FETCH calls in place of the ones in the script.
+
+ extract_downloads.bat
+ The "download" name must be replaced everywhere that a different
+ folder name is to be used as the location of the downloaded files
+ and of the new directories created as part of the extraction. Note
+ that all extractions of Zips are into a subfolder "T\" and then the
+ extracts are selectively moved to other places in the chosen download\
+ location. This procedure requires the greatest customization
+ depending on the purpose of the download procedure.
+
+ README.txt
+ replace with appropriate text, if needed at all.
+
+ customize.txt
+ this file can be kept unchanged or touched-up slightly for the new
+ location. Alternatively, simply refer to the originals that were
+ customized, linking to where this procedure was found.
+
+ maintenance.txt
+ This can still apply, depending on how much difference there is,
+ especially in the extraction process. Most of the advice remains
+ applicable.
+
+ unzip-win.js
+ This helper script takes the archive filename and the destination
+ folder as parameters. It does not need to be modified.
+
+ wget-win.js
+ This helper script takes the URL and the download location as
+ parameters. It does not need to be modified.
+
+
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+TODO
+
+ * Add maintainance.txt for the maintenance procedure for the scripts in their
+ original external\ portion of the Corinthia repository.
+
+ * Add customize.txt for the procedure for customizing the scripts in another
+ location or project.
+
+ * Update README.txt to reflect these when present.
+
+ * Add Apache license notice to anything of much length.
+
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+ 1.0.0 2015-01-08-16:48 Create initial version to account for the way
+ the scripts will produce different download folders in other places.
+
+ *** end of customize.txt ***
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-corinthia/blob/2d963742/external/external.txt
----------------------------------------------------------------------
diff --git a/external/external.txt b/external/external.txt
new file mode 100644
index 0000000..4846554
--- /dev/null
+++ b/external/external.txt
@@ -0,0 +1,76 @@
+external.txt 1.0.0 UTF-8 2015-01-08
+
+ CORINTHIA EXTERNAL DOWNLOADS FOR WINDOWS x86 BUILDS
+ ===================================================
+
+ The external\ folder holds scripts and the download\ sub-folder for
+ external software that Corinthia Windows Win32 x86 builds depend on.
+
+ Note: This repository folder is intended to be usable when cloned to a
+ Microsoft platform. The notation for file paths reflects that, even
+ though POSIX path notation is used in the git and when viewed on GitHub.
+
+
+MANIFEST
+
+ external.txt
+ This summary, manifest and work-item file for activity in this
+ external folder
+
+ .gitignore
+ Rule for excluding the download\ subfolder from the repository
+
+ extract_downloads.bat
+ Windows console session batch file for fetching and extracting
+ the external packages
+
+ fetch_downloads.bat
+ Windows console session batch file for fetching the external
+ packages to download\ without extracting anything; used by
+ extract_downloads to retrieve any packages not downloaded yet
+
+ README.txt
+ general description of the procedures and their usage
+
+ customize.txt
+ description of general procedure for customizing the procedures
+ in creating downloads on Windows for other purposes
+
+ maintenance.txt
+ description of the basic maintenance and modification-testing when
+ these procedures are updated and/or customized
+
+ unzip-win.js
+ helper JScript file used by extract_downloads to extract all
+ of the files in a Zip into a specified desktop folder
+
+ wget-win.js
+ helper JScript file used by fetch_downloads to make web requests
+ for downloading of specified URLs to specific download locations.
+
+
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+ 1.0.0 2015-01-08-21:14 Create initial version to account for the files in
+ the external\ folder
+
+ *** end of external.txt ***
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-corinthia/blob/2d963742/external/extract_downloads.bat
----------------------------------------------------------------------
diff --git a/external/extract_downloads.bat b/external/extract_downloads.bat
index a431567..ffeedf2 100644
--- a/external/extract_downloads.bat
+++ b/external/extract_downloads.bat
@@ -1,5 +1,5 @@
@echo off
-rem extract_downloads.bat 1.01 UTF-8
+rem extract_downloads.bat 1.1.0 UTF-8
rem EXTRACT THE EXTERNAL DOWNLOADS TO INCLUDE, LIB, AND BIN FOLDERS
rem Fetch downloads in case not done yet
@@ -44,10 +44,12 @@ rem path segments each ending with "\".
:SDL2x86
rem taking T\%2include and T\%2lib\*.lib across, with T\%2lib\*.dll to bin
+rem move any license *.txt files to the bin also.
CALL :UNZIP %1
XCOPY "%~dp0download\T\%2include\*.*" "%~dp0download\include" /I /Q /Y >nul
XCOPY "%~dp0download\T\%2lib\x86\*.lib" "%~dp0download\lib" /I /Q /Y >nul
XCOPY "%~dp0download\T\%2lib\x86\*.dll" "%~dp0download\bin" /I /Q /Y >nul
+XCOPY "%~dp0download\T\%2lib\x86\*.txt" "%~dp0download\bin" /I /Q /Y >nul 2>&1
EXIT /B 0
:ICONV
@@ -112,10 +114,12 @@ ECHO: *** No extractions have been performed.
ECHO:
EXIT /B 2
-rem 1.01 2015-01-02-17:03 Silence warnings when removing non-existent
-rem directories
-rem 1.00 2015-01-02-16:25 Complete Full-Functioning Externals Extraction
-rem Delivering the download\include, donwload\lib, and download\bin
-rem collections established for the current external downloads.
+rem 1.1.0 2015-01-08-14:41 Extract SDL2 Licenses
+rem The license files are added to the bin\ extraction.
+rem 1.01 2015-01-02-17:03 Silence warnings when removing non-existent
+rem directories
+rem 1.00 2015-01-02-16:25 Complete Full-Functioning Externals Extraction
+rem Delivering the download\include, donwload\lib, and download\bin
+rem collections established for the current external downloads.
rem *** end of extract_downloads.bat ***
http://git-wip-us.apache.org/repos/asf/incubator-corinthia/blob/2d963742/external/fetch_downloads.bat
----------------------------------------------------------------------
diff --git a/external/fetch_downloads.bat b/external/fetch_downloads.bat
index 0d5309b..08a815b 100644
--- a/external/fetch_downloads.bat
+++ b/external/fetch_downloads.bat
@@ -1,5 +1,5 @@
@echo off
-rem fetch_downloads.bat 1.00 UTF-8
+rem fetch_downloads.bat 1.1.0 UTF-8
rem FETCH EXTERNAL ARCHIVES FOR NATIVE WINDOWS BUILDS OF CORINTHIA
MKDIR "%~dp0download" >nul 2>&1
@@ -18,22 +18,23 @@ EXIT /B 0
IF EXIST "%~dp0download\%~n1%~x1" EXIT /B 0
rem do not download an archive that is already present.
Cscript /nologo "%~dp0wget-win.js" //B "%1" "%~dp0download\%~n1%~x1"
+rem This procedure always succeeds. It needs some error handling.
IF EXIST "%~dp0download\%~n1%~x1" ECHO: %~n1%~x1% downloaded
EXIT /B 0
+
rem TODO
-rem * Might want to pass up and act on error codes from the individual
-rem :FETCH operations.
rem * It might be handy to fetch these URLs from a file so that it can
rem be kept maintained in one place, even though the win32 cases are
rem unique to building for Windows.
-rem * Silent the warning on download folder already existing
rem XXX
rem * wget-win.js does not do FTP. So alternative locations have been
rem used for iconv and libmxl2.
-rem 1.00 2015-01-02-16:51 Complete with mating to extract_downloads.bat
-rem The tested version is adjusted to list successful downloads
-rem and not any that are not needed or fail.
+rem 1.1.0 2015-01-08-18:42 Adjust to line up with maintenance description
+rem The TODO list is updated. The always successful :FETCH noted.
+rem 1.00 2015-01-02-16:51 Complete with mating to extract_downloads.bat
+rem The tested version is adjusted to list successful downloads
+rem and not any that are not needed or fail.
rem *** end of fetch_downloads.bat ***
http://git-wip-us.apache.org/repos/asf/incubator-corinthia/blob/2d963742/external/maintenance.txt
----------------------------------------------------------------------
diff --git a/external/maintenance.txt b/external/maintenance.txt
new file mode 100644
index 0000000..17c6c21
--- /dev/null
+++ b/external/maintenance.txt
@@ -0,0 +1,166 @@
+maintenance.txt 1.0.0 UTF-8 2015-01-08
+
+ MAINTAIN THE EXTERNAL DOWNLOADS PROCEDURES
+ ==========================================
+
+ The external\ folder holds scripts that provide for specific downloads
+ to be obtained over the internet and retained in a download\ sub-folder.
+ The scripts also provide for the extraction of code and libraries from
+ the downloaded archives and making them available for use in builds on
+ Windows and in deployed packages on Windows.
+
+ When the source or version of downloads change, and other downloads are
+ added, these procedures must be maintained. Almost all of the maintenance
+ and related customization is in the two procedure fetch_downloads.bat
+ and extract_downloads.bat.
+
+ There are interdependencies among the two scripts and within the second
+ script that must be maintained and carefully verified.
+
+ This file provides guidance on how to preserve correct, tested operation
+ as maintenance and customization are performed.
+
+MAINTAINING FETCH_DOWNLOADS.BAT
+-------------------------------
+
+CREATING THE DOWNLOAD\ SUB-FOLDER
+
+This file creates the download\ subdirectory in the same folder as the script
+when it is not present already. It does not remove anything from a folder
+that is already there.
+
+The single command
+
+ MKDIR "%~dp0download" >nul 2>&1
+
+accomplishes that. The script parameter %~dp0 uses the drive and path of
+the location of the script itself (ending in "\") and appends the download
+name for the desired subdirectory. (This scheme is used throughout the
+scripts.) Any console output is routed to nul, and any error message output
+is routed to the same place as the console. This eliminates nuisance warnings
+about directories already existing, etc.
+
+DOWNLOADING THE EXTERNAL CONTENT
+
+Each download is accomplished with one of the lines that performs a
+CALL :FETCH operation. The one parameter on the same line is the full URL
+of a file to download.
+
+There are two important variables to observe. The full URL must be the
+complete location for accessing the file on the Internet using HTTP. The
+downloads must use HTTP in this implementation.
+
+Furthermore, the name by which the download will be stored will be the
+file name at the end of the URL. The :FETCH procedure takes apart the
+URL and specifies the correct file name to use when storing in the download\
+folder.
+
+The fetch_downloads.bat procedure is mostly silent. If it is discovered
+that a file to be downloaded is already present, it is left intact and not
+downloaded again. If there is a download operation, and the file is present
+afterwards, the name of the file is announced on the console. And if that
+download fails, there is also silence.
+
+TESTING AND TROUBLE-SHOOTING
+
+If there is any doubt about a download, the easiest way to determine if it
+is working is by putting the URL in the address bar of a browser and seeing
+whether the file is delivered.
+
+It is possible to run fetch_downloads.bat multiple times. Once all of the
+files are all present (if downloadable), there will be no further output.
+Look in the download\ directory to see what files are present.
+
+It may be necessary to trouble-shoot collisions of names that are the same
+when case is ignored, and there can be other problems with special characters
+that are not permitted in Windows file names (or that are reserved names, like
+"nul").
+
+Finally, the wget-win.js never fails, and it will always store *something*
+at the destination location. This can lead to file-not-found messages in the extract_downloads.bat script.
+
+
+MAINTAINING EXTRACT_DOWNLOADS.BAT
+---------------------------------
+
+The extract_downloads.bat script first does a CALL fetch_downloads.bat. This
+does no harm and it automatically obtains the downloads if they are not there
+already.
+
+CHECKING THAT THE DOWNLOADS ARE PRESENT
+
+The first part of extract_downloads.bat is a series of CALL :CHECK commands.
+Each one of these names one of the downloads that should now be present.
+If they are not all there, the procedure will report that and stop.
+
+The important feature of the CALL :CHECK commands is they must list exactly
+the same files that are specified in the CALL :FETCH commands in
+fetch_downloads.bat. These are the names the files should have been stored
+with.
+
+It is possible that a file is present but it is incorrect. This will usually
+show up with unusual results from the extract operations.
+
+PERFORMING EXTRACTIONS
+
+The actual extraction procedure is very specific to the individual downloads.
+There is some abstraction into general, reusable procedures, but they are
+still very specific to the nature of the download.
+
+There is a consistent extraction API for these custom routines. The first
+parameter is the name of the downloaded file. This should agree with the
+name in the CALL :CHECK operation.
+
+The second parameter indicates where inside of a Zip, the interesting data
+starts. Many of the Zip files unload a single directory as their top level
+and then the actual payload is at the level below that directory. When that
+is the case, the path prior to the payload is specified with a non-empty
+second parameter.
+
+This can be seen by examining some of the calls and comparing with how the
+Zip files are organized by inspecting them in the Windows file system.
+
+What's important:
+ 1. When an existing download is upgraded to use a new version, the file name
+ will change and so many any second parameter, since it often is a folder
+ whose name is based on the version of the related library.
+ 2. When an existing download is upgraded, the structure of the main material
+ may change, so a different set of XCOPY operations may be required to
+ extract the material correctly.
+
+This is even more involved when a new custom download is introduced.
+
+TESTING AND TROUBLESHOOTING
+
+The easiest way to test individual extractions is to remark-out all of the
+CALL procedures but the one to be tested. The extraction from the one
+archive can be seen in the download\T\ folder, and one can verify the
+download\include\, download\lib\, and download\bin results manually.
+
+
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+ 1.0.0 2015-01-08-19:12 Create initial version to account for the way
+ the scripts operate and will need to be modified on upgrades of
+ any of the downloads.
+
+ *** end of maintenance.txt ***
\ No newline at end of file