--- /dev/null
+README.win32.cygwin.txt
+-----------------------
+
+Building cpmtools-2.9 in Windows XP using:
+
+- cpmtools http://www.moria.de/~michael/cpmtools/
+- cygwin and the ncurses library - http://www.cygwin.com/
+
+"The experts will always complain about shorter documents that do do not
+provide enough details to confuse the rest of us, and longer documents that
+do not omit enough details to confuse the rest of us. No documentation is
+needed for people of that calibre."
+
+- Bill Buckels, November 2008
+
+This document is provided in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+A PARTICULAR PURPOSE. In particular, Bill Buckels has no warranty obligations
+or liability resulting from its use in any way whatsoever. If you don't agree
+then don't read it.
+
+Introduction
+------------
+
+This document is intended as a general guideline. An annotated summary is
+provided directly below especially for expert users followed by annotated
+details.
+
+Please review the other documentation and source code that comes with
+cpmtools for more information about cpmtools. Please review the cygwin
+documentation for more information about cygwin.
+
+At time of this writing, I have used the latest versions of the packages
+listed above to build the latest version of cpmtools in its entirety. I have
+documented the steps I followed below.
+
+Although there are probably other environments and compilers that can build
+cpmtools for Windows I have not been successful in using the other several I
+tried. Using a complete cygwin installation I had no problems and I had
+cpmtools built in moments after I had cygwin installed and the cpmtools
+source in place as documented below.
+
+Intended Audience
+-----------------
+
+This document takes two tracks for installing cpmtools binary executables
+after they have been built in cygwin:
+
+1. End users who will run cpmtools from within the cygwin shell. This
+includes unix users who do not want to use the native Windows command line.
+
+2. End users who will run cpmtools from the native Windows command line. The
+average Windows user does not have cygwin, and probably won't want to install
+cygwin or learn a unix-like shell to use cpmtools.
+
+The consideration here is where cpmtools looks for its CP/M disk format
+definitions file (diskdefs) when not in a unix-like environment like cygwin
+and this consideration will affect the way you build cpmtools since this path
+is hardcoded into the binary executables.
+
+My hope is that this document will help address the needs of both types of
+Windows end users and those who wish to provide cpmtools to them.
+
+Summary
+-------
+
+- Install cygwin with ncurses.
+- Download cpmtools-2.9.tar.tar to your cygwin home directory.
+- Start cygwin from the shortcut on the Windows desktop.
+
+- Enter the following commands:
+
+tar -xvf cpmtools.tar.tar
+cd cpmtools-2.9
+./configure --with-diskdefs=/usr/local/share/diskdefs
+make
+mkdir /usr/local/share
+mkdir /usr/local/share/man
+mkdir /usr/local/share/man/man1
+mkdir /usr/local/share/man/man5
+make install
+
+Assumptions
+-----------
+
+The above builds cpmtools under cygwin for end users who will use cpmtools in
+the cygwin shell and who will use the default installation.
+
+I am assuming in this summary that all has gone well and that anyone who
+deviates from what I have done or who has customized their cygwin
+installation will be able to troubleshoot their own problems,
+
+I therefore make the following related assumptions in this summary:
+
+- That compiler related programs and libraries required to build cpmtools
+under cygwin (including ncurses) are installed.
+
+- That you wish to download into and work under your home directory. You may
+also consider whether a better place to download is in /usr/local/src and
+whether you should install in the binaries in /opt/cpmtools/ and things of
+that nature.
+
+Default Format
+--------------
+
+You can change the default format to accomodate the special needs of your
+users so they don't need to type their favorite format. The following line
+can be entered to configure for an apple-do default format:
+
+./configure --with-defformat="apple-do" --with-diskdefs=/usr/local/share/diskdefs
+
+Native Windows Installation
+---------------------------
+
+If you wish to distribute your binaries to Windows end users who will not
+have the cygwin shell and who will use the Windows command line, you have 2
+options:
+
+1. Require your users to always work in the same directory as diskdefs.
+
+- or -
+
+2. Hardcode the default diskdefs path into your binary executables and
+require your users to always use the expected directory for diskdefs.
+
+The following line shows how to configure for an apple-do default format and
+to set the default diskdefs path in a mannner that is acceptable to Windows
+to a relative path from the root of the current drive:
+
+./configure --with-defformat="apple-do" --with-diskdefs=/cpmtools/diskdefs
+
+Cross-Cygwin Binary Installation
+--------------------------------
+
+You can still use the binaries built as above and installed using "make
+install" in cygwin if you add the following line to /etc/fstab (assuming your
+cygdrive is the Windows C:drive):
+
+c:\cygwin\usr\local\share /cpmtools
+
+Making a Zip Installation for Native Windows Users
+--------------------------------------------------
+
+If your target is the Windows user who does not have cygwin you can do the
+following in cygwin in your build directory to create a zip file that will
+contain the cpmtools binary executables:
+
+- mkdir cpmtools
+- cp *.exe cpmtools/.
+- cp diskdefs cpmtools/.
+- cp /bin/cygwin1.dll cpmtools/.
+- cp /bin/cygncurses-8.dll cpmtools/.
+- zip -R cpmtools/*.*
+
+Making Documentation for Native Windows Users
+---------------------------------------------
+
+If you wish to provide the cpmtools manual pages in html format you can use
+man2html to generate your html in ugly format and redirect to a file and edit
+by hand. Here's an example:
+
+man2html -r cpm.5 > cpm.html
+
+If you wish to avoid html and provide the cpmtools manual pages in text
+format you can use troff to generate your text in ugly format and redirect to
+a file and edit by hand. Here's an example:
+
+troff -a cpm.5 > cpm.txt
+
+This concludes the summary.
+
+Details, Alternatives, and Other Fluff
+--------------------------------------
+
+1.cygwin
+--------
+
+Cygwin gave me a complete and free environment to both configure and build
+cpmtools in its entirety.
+
+I installed cygwin from http://www.cygwin.com/ in its entirety which included
+the ncurses library and when prompted to select a download site I chose
+ftp://mirrors.kernel.org/sourceware/cygwin/
+
+The site you pick will depend on your own preference and how much of cygwin
+you decide to install will be up to you. I have a good Internet connection
+and a large hard disk so installing ALL of cygwin was no problem for me.
+Those who don't may wish to attempt an incremental installation which I
+personally found to be annoying and tedious.
+
+It is not necessary to install ALL cygwin options. Another alternative is to
+take the minimalistic approach and just install the compiler related
+programs and libraries required to build cpmtools (including ncurses). If you
+have missed something you will still be able to select additional components
+via Cygwin Setup.
+
+By default cygwin installs into c:\cygwin and puts a shortcut on the Windows
+desktop. By default the cygwin shell starts in your cygwin home directory
+under c:\cygwin\home\. I used the cygwin default paths for my installation of
+cygwin.
+
+2. cpmtoools
+------------
+
+I then downloaded Download cpmtools-2.9 from
+http://www.moria.de/~michael/cpmtools/
+and used WinRAR to extract cpmtools-2.9 to
+C:\cygwin\home\bbuckels\cpmtools-2.9\
+
+I have noted in the summary that tar can be used. Use whatever you are
+comfortable with to handle things from unix of a tarball nature.
+
+3. Building
+-----------
+
+3.1. I started cygwin by clicking on the cygwin shortcut on my desktop which
+placed me into my cygwin home directory in the cygwin shell.
+
+3.2 Now in the cygwin shell, I changed to the cpmtools directory by typing
+the following and pressing the [Enter] key:
+
+cd cpmtools-2.9
+
+
+3.3 Running the configure script
+--------------------------------
+
+Before making cpmtools, the configure script must be run to create the
+cpmtools makefile and the config.h header file required by cpmtools.
+
+I ran the configure script with two options; to set the default format for
+cpmtools to Apple II DOS 3.3 disk images and to tell cpmtools where to find
+the diskdefs format definitions file (which is required to run cpmtools. See
+far below.)
+
+3.3.2 Building for use in the cygwin shell
+------------------------------------------
+
+If I was building for use in the cygwin shell and I was using the default
+paths used by "make install" noted far below, to be certain that my diskdefs
+file would be found and to set my default format to "apple-do" I would type
+the following and press the [Enter] key:
+
+./configure --with-defformat="apple-do" --with-diskdefs=/usr/local/share/diskdefs
+
+3.3.1 Building for the Native Windows command line
+---------------------------------------------------
+
+To set the default format to "apple-do" and to provide a relative path for
+native Windows to my diskefs file which I would later copy to C:\cpmtools\ ,
+I typed the following and pressed the [Enter] key:
+
+./configure --with-defformat="apple-do" --with-diskdefs=/cpmtools/diskdefs
+
+Note: Windows paths are typed into the Windows native command line with
+backslashes in the MS- DOS tradition. Historically the forward slash used by
+unix as a path separator was used as a switch character in MS-DOS utilities
+and this has carried forward with the commands that come with Windows. But in
+a program, local Windows paths can be used with forward slashes instead and
+they still work. Backslashes will cause problems for configure so use forward
+slashes.
+
+3.4. The configure script created my cpmtools makefile and config.h with the
+options I chose. I then ran make by typing the following and pressing the
+[Enter] Key.
+
+make
+
+This concludes the first part of the details section of this document and I
+have covered the basic steps that I followed to build cpmtools. What you do
+will likely be a close variation.
+
+4. Installing
+-------------
+
+4.1 Some of this is also noted in the summary. Also keep in mind that if
+cpmtools is used outside of cygwin access to the documentation which is in
+the form of unix-style man pages will not be available unless reformatted to
+a media type that Windows users are familiar with.
+
+4.1.1 Installing for the cygwin shell
+-----------------------------------
+
+You can review the summary and the cpmtools INSTALL document for more
+information on unix-like installations. Installation of cpmtools for use in
+the cygwin shell follows those conventions.
+
+If installing cpmtools to be used in cygwin using the cpmtools defaults and
+assuming the directories below don't already exist, you will need to manually
+create the following directories using the mkdir command as follows:
+
+mkdir /usr/local/share
+mkdir /usr/local/share/man
+mkdir /usr/local/share/man/man1
+mkdir /usr/local/share/man/man5
+
+This is because the manual pages (man pages) will not be installed if you
+don't. If you install the man pages, then when you need help on cpmtools in
+cygwin, you can just enter "man cpmls" or "man cpmchmod", etc.
+
+After you make the directories above enter the following command:
+
+make install
+
+Assuming all has gone well, cpmtools is now part of your cygwin installation
+and can be used wherever you work in cygwin.
+
+4.1.2 Installing for Use Outside Cygwin
+---------------------------------------
+
+Please also read the summary.
+
+The requirements of my installation were to create a directory structure for
+a binary executable version of cpmtools targetted at Apple II disk image
+users that would run at the native Windows cmd prompt. I offer the following
+for general reference. The cygwin paths are based on my installation of
+cygwin and are presented using conventional windows pathname notation.
+
+4.1.2.1 Dll's
+-------------
+
+Two dll's from the c:\cygwin\bin\ directory were required:
+
+cygwin1.dll
+cygncurses-8.dll
+
+Regardless of installation, for this cygwin and this ncurses version access
+to these dll's will be required by this version of the cpmtools excecutables.
+
+4.2 Manually Placing Files for Use Outside Cygwin
+-------------------------------------------------
+
+I did my installation by hand.
+
+My executables were created in c:\cygwin\home\bbuckels\cpmtools-2.9\ (my
+cygwin home directory) which is also where the diskdefs file was.
+
+I used Windows Explorer to manually do the following:
+
+4.2.1 create c:\cpmtools\ directory.
+4.2.2 copy all 8 exes into c:\cpmtools\
+4.2.3 copy both dll's listed above into c:\cpmtools\
+4.2.4 copy diskdefs into c:\cpmtools\
+
+This gave me my directory structure and files for testing and distribution.
+
+I also placed an Apple II CP/M disk image called EXMPLCPM.dsk in c:\cpmtools\
+as a test target.
+
+
+5. Additional Notes
+-------------------
+
+5.1 diskdefs - CP/M disk format definitions
+--------------------------------------------
+
+The diskdefs file is a plain ascii text file that serves as a database of
+disk and disk image format definitions. It can be reviewed for available CP/M
+formats and their names. For Apple II CP/M 80 users the disk image formats
+apple-do and apple-po are available.
+
+The possible locations where cpmtools first looks for the diskdefs file:
+
+- Can vary depending on the preferences of the person who builds the cpmtools
+binaries (executables) from the source code.
+
+- The location is also installation dependent and the diskdefs file may also
+have been renamed (but we hope not).
+
+If it's not found the current (work) directory is then searched for a file
+called diskdefs.
+
+On a unix-like system, a ${prefix}/share/ style path like /usr/local/share/
+is a possible place that cpmtools could be made to first look for diskdefs.
+
+In a Win32 system sometimes unix-like shells like cygwin are used to run
+cpmtools instead of Windows cmd. For those installations unix-like
+conventions probably should apply.
+
+For cpmtools installations targetted at the average Windows user who does not
+have a unix-like shell and uses the Windows cmd prompt to run cpmtools there
+is no standard shared place that cpmtools can be made to first look for
+diskdefs. Pathed File names like \cpm\diskdefs or even c:\cpmtools\diskdefs
+are possible.
+
+5.2 Difficulties in using the Windows File System
+---------------------------------------------------
+
+This is not a troubleshooting guide. Unless you wish to find-out for yourself
+as I did just how many problems you can face with all of this, or you are
+really an expert, please do yourself a favour and try to stay within what I
+am suggesting as standard or alternative ways of building cpmtools.
+
+Missing libaries and compiler tools can be solved by trial and error and
+reading the cygwin and cpmtools documentation.
+
+There are however some things about path names and file names that you need
+to be aware of, some of which I have mentioned throughout this document and
+some which I deliberately did not mention yet, like avoiding absolute paths
+and drive letters.
+
+If you use a drive letter like C: when hardcoding a path to diskdefs you are
+making several assumptions:
+
+First off, you are assuming that your build of cpmtools will only be run from
+within Windows cmd shell on the local drive C:, (not from a bash-like shell
+like cygwin which doesn't support drive letters the same way Windows cmd and
+Windows itself does), and that diskdefs will not be on another drive, and
+that drive C: exists in the first place, and that diskdefs is not on a
+Windows network either unless drive C:,X:,Y:,Z:,etc is a mapped network
+drive. It is questionable whether cpmtools build process for diskdefs pathing
+supports UNC pathing anyway. I couldn't get \\ to work since the first slash
+disappears in the configure script and the second slash becomes an escape
+sequence for the next letter.
+
+Relative pathing will work and if you want to use conventions like
+/cpmtools-2.9/diskedefs this will work. Environments like ${USERPROFILE}
+aren't a good idea even if I could have got them to work since they are not
+portable for several reasons and I will say no more on this except I
+recommend that any path that you decide to use for diskdefs will only be
+almost portable between shells if off the root directory and contains forward
+slashes and no drive letters or colons.
+
+I hope what I have said proved less confusing to read than to write if you
+have bothered to read it. If you are not confused yet read further.
+
+- Since cpmtools has special meanings for A: and B: as command line targets
+it probably isn't a good idea to use these drives especially.
+
+- Some programmers and users have no difficulty in shifts between unix-like
+and Windows pathing. Some will be familiar with how colons are used on
+systems like Mac OSX. I think the only point to be made here is to consider
+your target audience and all the things you can anticipate going wrong with
+interoperability of all of this, (cpmtools being a set of command line
+tools), and build cpmtools accordingly for the needs of you or your users,
+then test what you have built with all this in mind.
+
+5.3 Testing your build of cpmtools
+----------------------------------
+
+To test what you have built I suggest you start with cpmls and cpmcp and an
+apple disk image or equivalent.
+
+John Elliot said "If you have appropriate rights, the CPMTOOLS should be able
+to access the floppy drive by using "A:" or "B:" as the name of the disc
+image.". I say don't bother mucking with your physical disk drive unless you
+have a physical CP/M disk of a format supported by cpmtools safely in the
+drive.
+
+Get an apple CP/M disk image and use it for testing is what I suggest. The
+following examples assume you have an Apple II DOS 3.3 order disk image
+called EXMPLCPM.dsk for testing.
+
+To list the files:
+
+cpmls -f apple-do EXMPLCPM.dsk
+
+The following example shows how to copy a file from an Apple II DOS 3.3 order
+cpm disk image to the current directory:
+
+cpmcp -f apple-do EXMPLCPM.dsk bhead.c 0:bhead.c
+
+The following example shows how to copy a file to an Apple II DOS 3.3 order
+cpm disk image from the current directory:
+
+cpmcp -f apple-do EXMPLCPM.dsk 0:bhead.c bhead.c
+
+To test the other utilities in cpmtools like cpmrm, cpmchattr, cpmchmod,
+fsck.cpm and fsed.cpm, review the appropriate manpages for usage.
+
+Those are simple tests as well using an apple-do format disk image. For
+mkfs.cpm I will leave it to those more capable than I to decide what to do
+there. Compared to them I am merely dangerous.
+
+Acknowledgements and Stuff
+--------------------------
+
+Michael Haardt - for cpmtools in the first place and for his tireless and
+ongoing efforts in supporting cpmtools in the second.
+
+John Elliot - for bringing cpmtools to Windows.
+
+My focus is on Windows XP (and other Windows) users and making this available
+to them. At this point in time my focus is also on Apple II Z80 Softcard
+users. Thankfully Michael Haardt has considered Apple II disk images in
+cpmtools. My focus is also on the Aztec C Z80 MS-DOS cross-compiler which
+creates Apple II CP/M programs in Windows XP.
+
+Between Michael and John, with cpmtools I can now easily get these onto an
+Apple disk image and transfer the disk image over to my real Apple II which
+has a Z80 softcard clone using my Microdrive with a CF card and make a real
+CP/M disk from the image with DISKMAKER.8 or DSK2FILE then run my Aztec C
+CP/M programs using the real thing. I can also use the emulator that came
+with Apple II Oasis to run the disk image.
+
+Apparently nothing is missing from cpmtools for Windows XP that is available
+on cpmtools for unix-like systems and I am thankful for that. Hopefully you
+will be too.
+
+I would also like to acknowledge the following individuals from the
+comp.os.cpm and apple2.sys usenet newsgroups who gave their experience,
+thoughts and encouragement during my adventure with all of this and in no
+particular order:
+
+David Schmidt - for cygwin feedback.
+Udo Munk - for cygwin feedback.
+Peter Dassow - for cygwin feedback.
+Stevo Tarkin - for msys feedback.
+Volker Pohlers - for msys and pdcurses feedback.
+Rolf Harmann - for linux feedback.
+Richard Brady - who may or may not know watfor:)
+
+If I missed anyone, I thank them too. I am somewhat new to some of this and
+needed all the help I received. cygwin is now my friend.
+
+Bill Buckels
+bbuckels@mts.net
+November 2008
\ No newline at end of file
projects / debian / cpmtools / blobdiff