+++ /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