CPOC C Development System for the Psion 3a/3c ============================================= Version 0.93 15th November, 1997 INTRODUCTION ============ The CPOC system is an ANSI C development system for use on the Psion 3a (and compatible machines). For those who wonder where we derived the name CPOC, it is merely a bit of a play on both EPOC (the name of the Psion 3a operating system) and "C in my POCket" as a description of how it might be used. CPOC is provided in a number of variants hosted on different operating systems. Unlike the SIBO C SDK available from Psion, CPOC can be run directly on the Psion 3a/3c rather than on a PC attached via 3-link. The Psion 3a/3c variant does, however, have some restrictions on its capabilities due to the memory constraints imposed on programs that run on the Psion EPOC16 operating system. The CPOC system also includes an assembler. This can be used directly for those who wish to program in assembler rather than C. We would be interested in feedback from those who use CPOC in this mode to see if we can improve the facilities for the Assembler programmer. RELEASE STATUS ============== This release includes all program components necessary to generate and link code. What is NOT yet available is the set of C libraries that are required to link any non- trivial C program. This release includes the following components that are specific to running hosted on the Psion: - CPOC front-end - C Pre-processor - C Compiler - Syntax check phase - C Compiler - Code generation phase - Assembler - Linker - Librarian - Header Pack utility Those who have looked at variants of CPOC hosted on other platforms might wonder why the C Compiler is provided as separate Syntax check and Compile phases when on other platforms there is only a single phase. The reason the Psion 3a/3c hosted variant is in two phases is to make it possible to fit the compiler into the memory size constraints imposed by the Psion EPOC operating system. The fact that this split has happened is of no concern to the user as the relevant phases are run automatically by the CPOC front-end. The following components are available for use with CPOC regardless of the system on which it is hosted. The packed versions of the headers have been processed by the "Header Pack" utility to remove all comments and unnecessary white space - this makes them ideal for use on the Psion where space is at a premium. The unpacked versions of the headers include comments and white space for layout purposes which makes them much easier to use of actually want to look at their contents. - ANSI C Headers (packed and Unpacked). This is required by all systems. - Psion PLIB related headers (Packed and unpacked). - Psion remaining headers (packed and unpacked). The Psion specific headers are based on those supplied with the Psion C SDK and are distributed with the permission of Psion. Please note that the libraries we intend to supply will support only some of the routines listed in these headers. Also the fact that routines are listed in these headers is no commitment to supplying them in the future. What is missing at this point is the standard C library needed to link a program to produce the final program that can be run on the Psion 3a/3c. This is very close to being ready for final release, and we are making the source to what is completed available on our web site for those who want to look at what has so far been completed (and possibly be interested in supplying some of the missing routines). FUTURE DEVELOPMENTS AND HOPES ============================= The things that are now missing to provide a complete Psion hosted C development system are: - The building of a ANSI C conformant library Finally there are miscellaneous tools that would be useful. Examples are: - The MAKE project automation tool - A program debugging environment You will find that there are entries on some of the menus for the utilities that we think are most likely to actually get produced. If we cannot produce all the above to run natively hosted on the Psion 3a, we could still possibly produce much of it to run hosted on a PC. Feedback on whether this is actually likely to be of use would be welcomed. Our current thinking is that most potential users in the PC environment would probably already use the existing Psion SIBO C SDK. CPOC LIMITATIONS ================ The CPOC system is not intended to simply be a direct equivalent to the C SIBO SDK that is provided by Psion. To put things in perspective, there are still reasons why a serious developer might be still want to use the Psion C SDK rather than CPOC: - Printed documentation is provided. This is essential if you want to use the Psion specific libraries. - The TOPSPEED compiler provided with the Psion C SDK generates smaller and faster code than CPOC. - The Psion C SDK includes additional tools to support the Psion OOPS method of programming. - The Psion C SDK provides support for building Dynamic Link Libraries. - The Psion C SDK includes a Resource compiler - The Psion C SDK includes a debugger. There are no developments planned for CPOC that will address these issues HARDWARE REQUIREMENTS ===================== The CPOC system will NOT run on a minimal Psion configuration. If your system does not meet the at least the specifications mentioned below, then there is no real point in even trying to get it to run. A recommended minimum system would have the following available (either built in or via SSD's): - At least 512K of base memory. This implies at least one of the following models. Psion 3a 512K Psion 3a 1Mb Psion 3a 2Mb - About 150Kb of space for the base CPOC software. Flash SSD is suitable for this. If you add in optional components as well the size can grow to around 300Kb. - Additional RAM space for source files and temporary files. Typically a value of about 200-300Kb is sufficient, although if you have a lot of source on- line you might require more. - Space for any system header files you require. This would typically be held on Flash SSD. You will see from the above that you should not expect to be able to use the CPOC system on a minimal Psion 3a system. In practice, we (using 3a/512K models) find that the ideal configuration is about 0.5Mb RAM SSD (or more) for source files and temporary files, and about 0.5Mb Flash or RAM SSD (or more) for the system files such as the programs and include files. The CPOC system will not, therefore, run on the Psion 3a 256Kb model or the older Psion 3 as these do not have sufficient memory. FILES SUPPLIED AND INSTALLATION =============================== The CPOC Psion hosted package provides you all the components that are specific to running on the Psion 3a/3c system. The header files (and libraries when available) are supplied separately as the same header files and libraries are used by all variants of CPOC. Also available separately for use with the Psion 3a/3c variant of CPOC is the ELVIS editor. The "CPOC Psion hosted" package comprises the following files: CPOC3A.TXT Overview and installation instructions CPOC.APP front-end to the system CPOCDBG.APP front-end to the system (debug version) CPP.IMG Pre-Processor C86CHECK.IMG Compiler syntax checking phase. C86CODE.IMG Compiler code generation phase. AS86.IMG Assembler LD86.IMG Linker AR86.IMG Librarian PACKHDR.IMG Header Pack utility The recommended place to put all the CPOC files is to create a \CPOC\BIN directory on any drive and put all the program files into this directory. You can then install the CPOC.APP program using the Psion-I method. It is not necessary for all the CPOC software to be on one drive. The system will automatically search the \CPOC\BIN directory on all drives for any component. There are also a number of other places that are searched if not found here. For more details read the on-line help built into the CPOC program (press Psion-I for program location information). CPOC will create a file called CPOC.INI to hold your global preferences. This file will be updated dynamically as you change such preferences. Initially the CPOC.INI file will be created in the same directory as the CPOC.APP file. If this is not on a RAM drive, then it is recommended that you move the CPOC.INI file to a \CPOC (or a \CPOC\BIN if you prefer) directory on a RAM drive. Also while the CPOC system is in use you will create various project files (with .PRJ file extension). These should ideally be placed in the same location as the CPOC.INI file Note that the CPOC front end is supplied in two variants - a standard one and a debug one. You only need to install one of these. The difference between the two is that the debug variant has extra code to produce diagnostics on what is happening as it is run. This can be useful to us if you encounter any problems in the use of CPOC. If you are not worried about generating code, then you can omit installing the C86CODE.IMG, AS86.IMG, LD86.IMG and AR86.IMG programs. This is particularily suitable for those who are using the Psion in conjunction with the SIBO C SDK and merely wish a portable C editing/checking environment. The CPOC system can also make use of the ELVIS 'vi' style editor. We released the Psion 3a port of this package as a free-standing item as many use it independently of CPOC. The latest release of this editor (Release 7.1) has Psion style menus and help so that even those who are unfamiliar with the 'vi' editor syntax should be able to use it successfully. DOCUMENTATION ============= The basic CPOC system is designed to be used without the need for comprehensive documentation. We have therefore put all the information we think you will need for basic use of the system into the form of on-line help built into the CPOC front-end program. Once you have installed the CPOC front-end, pressing HELP should give you (we hope) enough information to use the system effectively. The HELP is (where relevant) context sensitive so that pressing HELP while on a dialog or menu option will bring up help specifically on that topic. If you think there is important additional material that we need to include in the help system then please let us know what it is. At a later stage we will make available detailed documentation for each of the programs underlying the CPOC system. These will be made available as separate items as only advanced users should (we hope) need this level of documentation. We have not included any basic information on C and how to program in C. We expect any prospective users to either already have this or to be prepared to obtain it from a suitable source such as a library or bookshop. HEADER FILES ============ We supply header files separately as they are relevant to all variants of CPOC. These include a number of package depending on whether you want header files that cover just the ANSI C requirements, or are also interested in those that cover Psion specific facilities. Psion have also graciously given permission to distribute include files based on material in the Psion C SDK. The terms of this distribution do mean, however, that there will be routines named in these headers that although available in the C SDK provided by Psion, are unlikely to be available in the CPOC variants of the libraries. Be warned that the full set of Psion header files is very large - particularily if you include the OOPS oriented ones as well. LIBRARIES (*** IMPORTANT ***) ========= CPOC libraries are NOT currently available although we hope that it will not be long before they are ready. This means it is NOT yet possible to use CPOC to generate a program that can be run on the Psion. The CPOC system uses a different file format to the Psion C SDK, so even those who have that package cannot use the libraries provided. The libraries will be provided separately as they are relevant to all variants of CPOC. These include a number of packages depending on whether you want libraries that cover just the ANSI C requirements, or are also interested in those that cover Psion specific facilities. However please note that we do not intend to provide libraries that cover the full range of Psion specific capabilities - initially we intend to just provide the most common routines from the PLIB (and possibly HWIF) libraries. TEMPORARY FILES =============== While the CPOC system is running, it will create temporary files to pass information between various phases of the compilation process. There must be sufficient space on the device set in the user preferences to hold these temporary files. It is recommended that you avoid using drive M: for these temporary files as this would impact the space available for the programs to use. CPOC will automatically delete these temporary files when they are no longer needed. SHAREWARE STATUS AND REGISTRATION ================================= We currently provide CPOC on a "freeware" basis. We do, however, reserve the right to switch it to a shareware basis at a later stage once development is complete. We have therefore built into the system a registration capability. For this release you can enter any value for the 'Your name' value - typically this would be your name but that is up to you. Then for the 'Registration key' field enter the following value: 0114f78e-7f02e2fd We reserve the right to cause this key to stop working when we make the 1.0 release of CPOC - we have not yet actually decided on whether to leave CPOC as a completely free product or make it into shareware with a (relatively) nominal charge. We would welcome, however, any feedback on the methods we have used to encourage registration. We think we have struck a good balance between not crippling the software, but also giving just enough incentive to make regular users decide to register. If by any chance anyone thinks that CPOC is already good enough to register even though it is not yet a requirement, then we are always happy to receive such registrations. We will treat such voluntary contributions as counting towards the shareware registration fee if we do decide that CPOC should be become shareware rather than freeware. We have not yet decided on the likely registration fee, but were thinking that something like 20 UK pounds (30 US dollars) would be about right - again feedback on whether you think would be prepared to register the finished product at this price. SOURCE AVAILABILITY =================== The source is not generally distributed as it is very large (several megabytes in size). The source for all components except the CPOC front-end are available if you want them from our web site. If you cannot access the web, then try one of the other contact routes mentioned for feedback. KNOWN LIMITATIONS AND CONSTRAINTS ================================= - Large files may fail to compile due to the memory constraints that are imposed on Psion programs. This limitation can be avoided if you keep down the size of your source files, and (most important) you limit the number of header files that you include. - It is not possible to compile Psion Object Oriented programs if they include the header file (which then includes LOTS of other header files) due to these memory constraints. This constraint can sometimes be avoided by only including those headers that you actually really need. FEEDBACK ======== Feedback will be welcomed. For details on the various methods whereby we can be contacted look up the help on the "About" menu item while running the CPOC front-end program. COPYRIGHT ========= The CPOC system is (c)copyright 1995-1997 by D.J. Walker and K.D. Walker All rights reserved. DISCLAIMER ========== Although CPOC has been extensively tested, the authors shall not be responsible for any loss of any kind due to its use. It is the user's responsibility to establish the suitability of the CPOC software for the use to which it to be put.