X-Git-Url: https://git.gag.com/?p=debian%2Fcpmtools;a=blobdiff_plain;f=README.win32.cygwin.txt;fp=README.win32.cygwin.txt;h=0000000000000000000000000000000000000000;hp=868e1e8c8e52cccbea7e582492f453e260fe57a9;hb=0244ff6db7cb417c6210118e14ebc8a11924b7f6;hpb=be51a0b47ec4edacc689851a88ec6172737cb61c diff --git a/README.win32.cygwin.txt b/README.win32.cygwin.txt deleted file mode 100644 index 868e1e8..0000000 --- a/README.win32.cygwin.txt +++ /dev/null @@ -1,518 +0,0 @@ -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