From 205e3003f83787f098370655a133b4890ae9461c Mon Sep 17 00:00:00 2001 From: Andy McFadden Date: Thu, 11 Dec 2014 20:11:33 -0800 Subject: [PATCH] Update the ReadMe files This ports the contents of ReadMe.htm to Markdown, splitting the Linux information out into a separate file. Specific instructions for building the Linux utilities are now included. --- README-linux.md | 68 +++++++++++ README.md | 210 +++++++++++++++++++++++++++++++- ReadMe.htm | 313 ------------------------------------------------ 3 files changed, 272 insertions(+), 319 deletions(-) create mode 100644 README-linux.md delete mode 100644 ReadMe.htm diff --git a/README-linux.md b/README-linux.md new file mode 100644 index 0000000..f40578f --- /dev/null +++ b/README-linux.md @@ -0,0 +1,68 @@ +CiderPress Linux Utilities +========================== + +CiderPress is a Windows app, but the code for accessing NuFX (ShrinkIt) +archives and disk images can be built as libraries on Linux and used +from applications. A few samples are provided. Most are really just +API demos, but they may come in handy. + +You need to build NufxLib, the diskimg library, and then the samples. + +Build Instructions +------------------ + +1. Configure and build NufxLib library + + cd nufxlib + ./configure + make + +2. build diskimg library + + cd ../diskimg + make + +3. build libhfs library + + cd libhfs + make + +4. build samples + + cd ../../linux + make + +The build system could use some work. + + +Sample Programs +--------------- + +The current sample programs are: + +`getfile disk-image filename` -- +Extract a file from a disk image The file is written to stdout. + +`makedisk {dos|prodos|pascal} size image-filename.po file1 ...` -- +Create a new disk image, with the specified size and format, and copy the +specified files onto it. The NON file type is used. + +`mdc file1 ...` -- +This is a Linux port of the MDC utility that ships with CiderPress. +It recursively scans all files and directories specified, displaying +the contents of any disk images it finds. + + +### Bonus Programs ### + +`iconv infile outfile` -- +Convert an image from one format to another. This was used for testing. + +`packddd infile outfile` -- +The DDD code was originally developed under Linux. This code is here +for historical reasons. + +`sstasm part1 part2` -- +The SST re-assembly code was originally developed under Linux. The code +is here for historical reasons. + diff --git a/README.md b/README.md index ac5bb03..9e11ac1 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,208 @@ -UNDER CONSTRUCTION +CiderPress +========== -I'm in the process of updating CiderPress to work with newer tools (VS 2013) and operating systems. +A Windows utility for managing Apple II file archives and disk images. + +CiderPress was initially sold by faddenSoft, LLC as a shareware product, +starting in March 2003. In March 2007, the program was released as +open source under the BSD license. + +- - - + +**UNDER CONSTRUCTION** + +I'm in the process of updating CiderPress to work with newer tools (VS +2013) and operating systems. Current status: -- Win32 main application properly executes basic functions. Still some things missing. Not well tested. +- Win32 main application properly executes basic functions. Not well tested. - MDC application seems to work; not well tested. -- Linux code doesn't compile. -- The web documentation has been moved to github (see the gh-pages branch) and is - available from http://a2ciderpress.com/. +- Linux code seems to work; not well tested. +- The web documentation has been moved to github (see the gh-pages branch) + and is available from http://a2ciderpress.com/. + +- - - + +Why Bother? +----------- + +Back in 2002 I decided it was time to learn how to write an application +for Microsoft Windows. I had been a professional software engineer for +many years -- including 2.5 years at Microsoft! -- but had never written +a Windows program more complex than "Hello, world!". + +I decided to write a Windows version of GS/ShrinkIt. I had already written +NufxLib, which handled all of the ShrinkIt stuff, so I could focus on +writing the Windows user interface code. + +Somewhere in the early stages of the project, it occurred to me that a +disk image isn't substantially different from a file archive. They're +both just collections of files laid out in a well-defined manner. The +decision to handle disk images as well as ShrinkIt archives seemed like +a simple improvement at the time. The rest is history. + +CiderPress has allowed me to explore a variety of interesting +technologies. It has five different ways of reading a block from physical +media, depending on your operating system and what sort of device you're +reading from. I was able to take what I learned from a digital signal +processing textbook and apply it to a real-world problem (decoding Apple +II cassette data). It is also my first Shareware product, not to mention +the initial product of my first small business venture (faddenSoft, LLC). + +I could have written other things. No doubt they would have made more +money. CiderPress is something that I find very useful, however, in the +pursuit of my Apple II hobby. + +Above all, this has been a labor of love. I have tried to get the details +right, because in the end it's the little things that mean the difference +between "good" and merely "good enough". + + +Source License +-------------- + +The source code to CiderPress is available under the BSD license. See +the file [LICENSE.txt](LICENSE.txt) for details. + +CiderPress requires three other libraries, all of which are included as +source code: + +- NufxLib, also available under the BSD license. +- Zlib, available under the Zlib license. +- libhfs, available under the GPL license. + +The license allows you to do a great many things. For example, you could +take the source code to CiderPress, compile it, and sell it. I'm not sure +why anyone would buy it, but you're legally allowed to do so, as long as +you retain the appropriate copyright notice. + +If you retain libhfs, any changes you make to any part of CiderPress must +be made available, due to the "viral" nature of the GPL license. If this +is not acceptable, you can remove HFS disk image support from CiderPress +(look for "EXCISE_GPL_CODE" in DiskImg.h). + + +Building the Sources +-------------------- + +The current version of CiderPress is targeted for Visual Studio 2013, +using the WinXP compatibility Platform Toolset to allow installation on +Windows XP systems. You should be able to select Debug or Release and +just build the entire thing. + +If you want to use the static analyzer, you will need to change the +Platform Toolset to straight Visual Studio 2013. + +A pre-compiled .CHM file, with the help text and pop-up messages, +is provided. The source files are all included, but generation of the +.CHM is not part of the build. If you want to update the help files, +you will need to download the HTML Help Workshop from Microsoft, and use +that to compile the help project in the app/Help directory. + +The installer binary is created with [DeployMaster](http://deploymaster.com/). + + +Building for Linux +------------------ + +The NuFX archive and disk image manipulation libraries can be used from +Linux. See the [Linux README](ReadMe-linux.md). + + +Source Notes +------------ + +Some notes on what you'll find in the various directories. + +### Main Application ### + +This is highly Windows-centric. My goal was to learn how to write a +Windows application, so I made no pretense at portability. For better +or worse, I avoided the Visual Studio "wizards" for the dialogs. + +Much of the user interface text is in the resource file. Much is not, +especially when it comes to error messages. This will need to be addressed +if internationalization is attempted. + +It may be possible to convert this for use with wxWidgets, which uses an +MFC-like structure, and runs on Mac and Linux as well. The greatest barrier +to entry is probably the heavy reliance on the Rich Edit control. Despite +its bug-ridden history, the Rich Edit control allowed me to let Windows +deal with a lot of text formatting and image display stuff. + +### MDC Application ### + +MDC (Multi-Disk Catalog) was written as a simple demonstration of the +value of having the DiskImg code in a DLL instead of meshed with the main +application. There's not much to it, and it hasn't changed substantially +since it was first written. + +### DiskImg Library ### + +This library provides access to disk images. It automatically handles +a wide variety of formats. + +This library can be built under Linux or Windows. One of my key motivations +for making it work under Linux was the availability of "valgrind". Similar +tools for Windows usually very expensive or inferior (or both). + +The basic classes, defined in DiskImg.h, are: + +- DiskImg. This represents a single disk image, which may have sub-images. +Operations on a DiskImg are roughly equivalent to a device driver: +you can read and write blocks, detect image formats, and create new +images. +- DiskFS. Paired with a DiskImg, this is roughly equivalent to +a GS/OS FST (FileSystem Translator). You can perform file operations +like rename and delete, format disks, see how much space is available, +and search for sub-volumes. +- A2File. Represents a file on a DiskFS. This holds the file's name, +attributes, track/sector or block lists, and provides a call to open +a file. +- A2FileDescr. Represents an open file. You can read or write data. +Sub-classes are defined in DiskImgDetail.h. Most applications won't need +to access this header file. Each Apple II filesystem defines sub-classes +of DiskFS, A2File, and A2FileDescr. + +In an ideal world, the code would mimic the GS/OS file operations. +In practice, CiderPress didn't need the full range of capabilities, +so the functions have some basic limitations: + +- On ProDOS and HFS, you can only open one fork at a time. This allowed me to use simpler data structures. +- Files are expected to be written in one large chunk. This reduced the complexity of the task enormously, because there's so much less that can go wrong. + +Some things that could be improved: + +- The overall structure of the filesystem handlers evolved over time. There is some amount of redundancy that could be factored out. +- The API, especially in DiskImg, could probably be simplified. + +The library depends on NufxLib and zlib for access to compressed images. + +### Reformat Library ### + +This is probably the most "fun" component of CiderPress. It converts +Apple II files to more easily accessible Windows equivalents. + +Start in Reformat.h and ReformatBase.h. There are two basic kinds of +reformatter: text and graphics. Everything else is a sub-class of one of +the two basic types. + +The general idea is to allow the reformatter to decide whether or +not it is capable of reformatting a file. To this end, the file type +information and file contents are presented to the "examine" function +of each reformatter in turn. The level of confidence is specified in a +range. If it's better than "no", it is presented to the user as an option, +ordered by the strength of its convictions. If chosen, the "process" +function is called to convert the data. + +Bear in mind that reformatters may be disabled from the preferences menu. +Also, when extracting files for easy access in Windows, the "best" +reformatter is employed by the extraction code. + +Most of the code should be portable, though some of it uses the MFC +CString class. This could probably be altered to use STL strings or plain. + +### Util Library ### + +Miscellaneous utility functions. + diff --git a/ReadMe.htm b/ReadMe.htm deleted file mode 100644 index 5cbe863..0000000 --- a/ReadMe.htm +++ /dev/null @@ -1,313 +0,0 @@ - - - - - - -CiderPress Source README - - - -

CiderPress Source README

-Release notes for v3.0.0
-Last updated: 25-Mar-2007 - -

Contents:

- - -
-

What's CiderPress?

-

CiderPress is a Windows utility for manipulating Apple II disk images -and file archives. It supports all major disk and archive formats used -on the Apple II and by Apple II emulators. -

CiderPress was sold by faddenSoft, LLC as a shareware product for about four -years, starting in March 2003. - - -

Why Bother?

- -

Back in 2002 I decided it was time to learn how to write an application for -Microsoft Windows. I had been a professional software engineer for many -years -- including 2.5 years at Microsoft! -- but had never written a -Windows program more complex than "Hello, world!". - -

I decided to write a Windows version of GS/ShrinkIt. I had already written -NufxLib, which handled all of the ShrinkIt stuff, so I could focus -on writing the Windows user interface code. - -

Somewhere in the early stages of the project, it occurred to me that a -disk image isn't substantially different from a file archive. They're -both just collections of files laid out in a well-defined manner. The -decision to handle disk images as well as ShrinkIt archives seemed like -a simple improvement at the time. The rest is history. - -

CiderPress has allowed me to explore a variety of interesting technologies. -It has five different ways of reading a block from physical media, depending -on your operating system and what sort of device you're reading from. I -was able to take what I learned from a digital signal processing textbook -and apply it to a real-world problem (decoding Apple II cassette data). It -is also my first Shareware product, not to mention the initial product of -my first small business venture (faddenSoft, LLC). - -

I could have written other things. No doubt they would have made more money. -CiderPress is something that I find very useful, however, in the pursuit of -my Apple II hobby. - -

Above all, this has been a labor of love. I have tried to get the details -right, because in the end it's the little things that mean the difference -between "good" and merely "good enough".

- -

License

- -

The source code to CiderPress is being made available under the BSD license:

- -
-Copyright (c) 2007, FaddenSoft, LLC
-All rights reserved. - -

Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: -

    -
  • Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. -
  • Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. -
  • Neither the name of FaddenSoft, LLC nor the - names of its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. -
-

THIS SOFTWARE IS PROVIDED BY FaddenSoft, LLC ``AS IS'' AND ANY -EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL FaddenSoft, LLC BE LIABLE FOR ANY -DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -

-CiderPress requires three other libraries, all of which are included as either -source or binaries: - -

The license allows you to do a great many things. For example, you could -take the source code to CiderPress, compile it, and sell it. I'm not sure why -anyone would buy it, but you're legally allowed to do so, as long as you retain -the appropriate copyright notice.

-

If you retain libhfs, any changes you make to any part of CiderPress must -be made available, due to the "viral" nature of the GPL license. If this is -not acceptable, you can remove HFS disk image support from CiderPress (look for -"EXCISE_GPL_CODE" in DiskImg.h).

- - -
-

Building the Sources

- -

How to build your own copy of CiderPress. - -

Windows

-

The sources are distributed with the necessary project/solution files for -Microsoft Visual Studio 6.0 and Microsoft Visual Studio 2003.  All you -really need is the C++ compiler.  The free or student editions of the -compilers will probably work. -

I usually work on CiderPress in Visual C++ 6.0, -and use that when building for distribution.  I chose to stick with 6.0 for -CiderPress because you need an additional MSVC DLL when you build with -2003.  Also, the newer tools cause the newer file selection dialogs to be -used, and the custom dialog code gets all wonky.

- - -

In 6.0, you need to select "app" as the build target (Build->Set -active configuration), and hit F7.  This will build everything except MDC, -which you can then build by selecting "mdc" and hitting F7.  You -can also configure a batch build.  In 2003 just select "build -solution".  The necessary prebuilt libraries should be there for both -"debug" and "release" builds.  (You can tell how it has -been built by looking at the version string in the About box.)

- - -

When the build completes, the necessary DLLs are copied around so you can -execute the binary by launching it within Visual Studio (hit F5).  You will -get a warning about not being able to find the NiftyList data file unless you -copy that from "DIST" into the app source directory.

- - -

The distribution comes with prebuilt versions of NufxLib2 and zlib in DLL -form.  If you like, you can download and compile your own.

- - -

There are two things you can't create with the standard tools:

- - - -

Compiled help files are included, so you can still generate a new version of -CiderPress even if you can't update the help.  You don't strictly need the installer either, though it is -quite handy, and the uninstaller will clean up the registry entries CiderPress -creates.

-

Linux

-

The "linux" directory has a few command-line utilities and a simple -makefile.  It will build the diskimg and HFS libraries, then the sample utilities:

- - - -

This are mostly intended for testing and illustration of the interfaces, but -they can be useful as well.  Some other code is also provided:

- - - -

The "prebuilt" directory has a pre-built copy of NufxLib, so you -don't have to build your own.

-

If you're planning to hack on this stuff, use "make depend" before -"make" to fill in the dependencies.

- - -
-

Source Notes

- -

Some notes on what you'll find in the various directories. - -

Main Application

- -

This is highly Windows-centric.  My goal was to learn how to write a -Windows application, so I made no pretense at portability.  For better or -worse, I avoided the Visual Studio "wizards" for the dialogs. - -

Much of the user interface text is in the resource file.  Much is not, -especially when it comes to error messages.  This will need to be addressed -if internationalization is attempted. - -

It may be possible to convert this for use -with wxWidgets, which uses an MFC-like structure, and runs on Mac and Linux as -well. The greatest barrier to -entry is probably the heavy reliance on the Rich Edit control. Despite -its bug-ridden history, the Rich Edit control allowed me to let Windows -deal with a lot of text formatting and image display stuff. - - -

MDC Application

- -

MDC (Multi-Disk Catalog) was written as a simple demonstration of the value of having the DiskImg -code in a DLL instead of meshed with the main application.  There's not -much to it, and it hasn't changed substantially since it was first written. - - -

DiskImg Library

- -

This library provides access to disk images.  It automatically handles a -wide variety of formats. - -

This library can be built under Linux or Windows. One of my key motivations -for making it work under Linux was the availability of "valgrind". Similar -tools for Windows usually very expensive or inferior (or both). - -

The basic classes, defined in DiskImg.h, are: -

-

Sub-classes are defined in DiskImgDetail.h.  Most applications won't -need to access this header file.  Each Apple II filesystem defines -sub-classes of DiskFS, A2File, and A2FileDescr.

- -

In an ideal world, the code would mimic the GS/OS file operations.  In -practice, CiderPress didn't need the full range of capabilities, so the -functions have some basic limitations: -

-

Some things that can be improved: -

- - -

The library depends on NufxLib and zlib for access to compressed images.

- - -

Reformat Library

-

This is probably the most "fun" component of CiderPress. It converts Apple II files -to more easily accessible Windows equivalents. - -

Start in Reformat.h and ReformatBase.h. There are two basic kinds of -reformatter: text and graphics. Everything else is a sub-class of one of the -two basic types. - -

The general idea is to allow the reformatter to decide whether or not it is -capable of reformatting a file. To this end, the file type information and -file contents are presented to the "examine" function of each reformatter in -turn. The level of confidence is specified in a range. If it's better than -"no", it is presented to the user as an option, ordered by the strength of its -convictions. If chosen, the "process" function is called to convert the data. - -

Bear in mind that reformatters may be disabled from the preferences menu.  -Also, when extracting files for easy access in Windows, the "best" -reformatter is employed by the extraction code.

Most of the code should be portable, though some of it uses the MFC CString class.  -This could probably be altered to use STL strings or plain. - - - -

Util Library

- -

Miscellaneous utility functions. - -

For a good time, look at SelectFilesDialog.cpp. - -

To enable debug logging for one of the applications, define _DEBUG_LOG in -MyDebug.h in this library. You will see "_DEBUG_LOG" in the version string -in the About box when this is defined. The log is written to C:\cplog.txt. -An existing log file will be appended to if the previous log was written to -less than 8 hours ago.

- -
-

Enjoy!

-
Andy McFadden
- - -