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