RISC DISC 2

home *** CD-ROM | disk | FTP | other *** search

/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / code / desklib / DeskLib / !DLSources / !Help < prev next >

Wrap

Text File | 1995-08-28 | 17.3 KB | 565 lines

!DLSources - DeskLib Sources application directory •••••••••••••••••••••••••••••••••••••••••••••••••• This application directory contains all DeskLib code-files except for the final libraries and headers, which are in the !DeskLib application. It sets the system variable <DeskLib_Sources$Dir> to be the !DLSources directory. This directory is *not* needed for writing applications which use DeskLib - the !DeskLib application contains all the headers and libraries needed. All source code for DeskLib is contained in this directory. The structure of this directory is rather different from previous DeskLib releases. This is partly because I've attempted to automate the creation of the various files needed for DeskLib, and because DeskLib is now available in DLL form, as well as the original statically-linkable 'DeskLib:o.DeskLib'. Code for DLLs has to be compiled with different flags from normal, so each DeskLib sublibrary now has two or three subdirectories contining differently-compiled .o files. In the 'Scripts' subdirectory, there are a few Obey files which can be used to do various things such as generate makefiles for each sub-library. See below for a description of what each one does. Please note that the version of the 'LibFile' program that comes with Acorn's Desktop C can crash the whole system very nastily if there isn't enough memory (it trashed my HD's boot block in doing so once). It seems to grab 1.5Mb if possible, so the scripts which actually call LibFile have a 'Wimpslot 1500k' to ensure there is enough space for LibFile to work in. This seems to be enough memory to build DeskLib at least. All of the scripts are of type 'TaskObey' so run in a taskwindow if double clicked. This probably slows down compiling, but I prefer to keep my system multitasking where possible. Everything should work fine if you settype them to be vanilla Obey files. The 'Bin' directory contains a few of programs which I use to do various things sycj as create makefiles in each DeskLib sublibrary directory. The 'Libraries' directory contains, as before, a separate directory for each DeskLib sub-library. Each has two or three makefiles which make the various files. These makefiles are now created automatically using template makefiles in the 'TemplateMF' directory. Remaking DeskLib ———————————————— This should be fairly straightforward: The file '!DLSources.Scripts.Static.MakeAll' will remake those parts of the static version of DeskLib that are out of date, by running Amu on each library's makefile. The file '!DLSources.Scripts.Static.MakeAll2' is more drastic - it deletes all the .o files, retrims the header files, remakes all the makefiles from the template makefiles in '!DLSources.TemplateMF', and then recompiles everything. The files '!DLSources.Scripts.Static+DLL.MakeAll' and '!DLSources.Scripts.Static+DLL.MakeAll2' are similar to the above, except that they also remake the dynamic-linking version of DeskLib. The file '!DLSources.Scripts.OtherLibs.MakeAll' remakes the libraries which aren't part of the main DeskLib library - Debug and SmallError. Dynamically Linked DeskLib sublibraries ——————————————————————————————————————— When making a client for use with DeskLib DLLs, link with 'DeskLib:o.DLLClient' (instead of 'DeskLib:o.DeskLib'). This file contains the stubs files of all DeskLib sublibraries available as DLLs, and suitably-compiled .o files from all the other sublibraries (for full information about making DLL clients, see '...Docs.DynamLink.SDLS_Apps'). This ensures that, when making a client to use DLL DeskLib, code for DeskLib functions not available as a DLL is linked in statically. Only about half of the DeskLib sublibraries have DLL versions. This is because it is not practical to make a DLL version of (say) WimpSWIs - for example, just one call to a Wimp SWI would involve loading the entire 5k WimpSWIs DLL into the RMA. Instead, the call is statically linked into the client. This is generally true for any DeskLib sublibrary which consists of many small unrelated functions. There is also what appears to be a 1.2k overhead when making a DLL, so very small DeskLib sublibraries (eg Sound) are also not available as DLLs. Other ————— To enable auto-generation of appropriate makefiles for the sublibraries and auto-generation of the final DeskLib libraries, sub-libraies which are available as DLLs have a zero-length 'IsDLL' file in their directory. Code for use in a DLL has to be compiled with various special cc flags, so every DeskLib sublibrary which has a DLL version has two different sets of .o files. These are in '<sublibname>.DLL' and '<sublibname>.Static'. In addition, every sublibrary which is not available as a DLL has three sets of .o files - for static linking, static linking with a DLL client, and static linking with a DLL. Fairly complete description of all files in this !DLSources directory ————————————————————————————————————————————————————————————————————— Here is what is where: !Boot Sets the system variable DeskLib_Source$Dir to point to this directory. Also sets DeskLib_Run$Path to point to the Bin subdirectory, and adds DeskLib_Run: to your Run$Path. Sets 'DeskLib_Commands:' to point to '!DLSources.Scripts.Commands.'. !Run Simply runs !Boot. !Help This file. !Sprites The !DLSources sprite - a green version of the normal DeskLib sprite. Bin. Some general utilities used by some of the scripts described below. They might be useful for non-DeskLib things as well. This 'Bin' directory is added to Run$Path. Every Runs a command on every file/dir in a directory. Just type 'Every' to get help. CTrim Strips comments from a C source file. Only overwrites the destination file if the new file differs. This is to allow modification of comments in h_doc headers, without forcing recompilation of hundreds of C files. TrimCRs Removes all CR characters from a file. Makatic Used to make makefiles suitable for a particular project directory, using a template makefile. IfExist Runs a command only of the specified file/dir exists. IfNotExist Runs a command only of the specified file/dir doesn't exist. Libraries. Every DeskLib sub-library's source, makefiles etc. <Lib-name>. Every sublibrary has the following source-directories: c. C source s. Assembler source h. Internal headers Every library also has the following directory: Static. All files for the conventional version of this sublibrary. Makefile The makefile Lib One-chr long file which has the date-stamp of the last creation date of this library. o. The .o files. DeskLib sublibraries which are not available as a DLLs —————————————————————————————————————————————————————— As well as the normal static .o files described above, there are two extra sets of .o files, in 'DLLClient' and 'DLL': <Lib-name>.DLLClient. All files needed when statically linking this sublibrary with a client application. The .o files are compiled with _DeskLib_SDLS_CLIENT predefined. MkClientOs This makefile compiles the source with _DeskLib_SDLS_CLIENT predefined. o. The .o files. DLL. All files needed when statically linking this sublibrary with a DLL. MkOs Compiles the source with cc -zM etc. o. The object files. DeskLib sublibraries which are available as a DLLs —————————————————————————————————————————————————— As well as the normal static .o files described above, there is one extra set of .o files in 'DLL' plus a few extra files which are needed to make the DLL version. <Lib-name>.DLL. Everything for making this sublibrary into a DLL. o. Object code compiled with special flags for use in SDLS DLLs: -zM -D_DLL etc. MakeStubsOs This makefile compiles all the .c files and makes the DLL Stubs file. PlainStubs Plain stubs file as created using SDLS's 'cdll' tool. OSObj An extra .o file which imports symbols from every Stubs file that this sublibrary references. This is an assembled version of 'OtherStubs' described below. Stubs The Stubs file for this sublibrary. This is simply the 'PlainStubs' and 'OSObj' object files partially linked together. MakeDLL This makefile makes the DLL by linking all the .o files with 'Header', DeskLib:o.DLLDLL and a few .o files which come with the SDLS. Header Intermediate file used to make the 'DLL' file. These are a few extra files in DLL library directories. OtherStubs Small assembler source. Only used when making DLL Stubs files. See '!DLSources.Docs.RndDLLInfo' for more information about this. DLLDef (Libraries.DLL.*. only) Text file which specifies what functions the DLL provides. If this is not present, the DLL makefile will use cdll to make a default one based on what .o files are present, but this will need modifying by hand. NB the DLLDef file is not in the 'DLL' directory because it is effectively a source file - it is tweaked by hand after generation by cdll. Hence keeping it outside the 'DLL' directory means that one can delete all the 'DLL' directories to save on disc space but still be able to restore all DLL information easily. IsDLL Zero-length file which is present only in sub-libraries which are available as DLLs. The presence/absence of this file is checked by the various DeskLib scripts so that different things are done to libraries which can/can't be made into DLLs. OtherLibs. A few libraries which aren't part of the main DeskLib library-files. Debugs. Some alternative debugging libraries Makefile This puts the different debugging libraries into <DeskLib$Dir>.o.Debug. o. c. SmallError. An alternative to the standard Error library. It sends error messages to stderr. Useful for using Error_Report* in command line programs. The generated library is '<DeskLib>.Other.SmError'. TemplateMF. Contains template makefiles for making static and dynamically-linked versions of the DeskLib sublibraries. These makefiles just need the macro $(ObjectFiles) to be set to be a space-separated list of .o files, and $(LibName) to be set to the name of the library, and they will compile/assemble etc as necessary. The 'Makatic' command is used to generate real usable makefiles from these templates in each of the sub-library directories. Static Produces standard .o files MakeDLL Links .o files with the DeskLib:o.DLLDLL library to make the finished DLL. MkStubsOs Compiles all .c/s files with flags suitable for making into a DLL. Uses cdll to make a stubs file. Uses cdll to generate a default Defs file if none is present. MkOs Compiles all .c/s files with flags suitable for linking statically with a DLL. Used for libraries which aren't available as a DLL. MkClientOs Makes .o files suitable for static linking with a client application. Used for libraries which aren't available as a DLL. ObjLists. Various text files which contain lists of .o files for use with LibFile to make the finished DeskLib libraries. Note that these lists are generated automatically by scripts before LibFile is called, so that they are always up to date. They take a few minutes to generate at the moment, because they use a rather clumsy system of calling Obey file CLI commands. DLLDLL List of all Stubs files, and all .o files from non-DLL sublibraries compiled for use in DLLs. ie. <DeskLib_Sources$Dir>.Libraries.DLL.*.DLL.Stubs <DeskLib_Sources$Dir>.Libraries.Static.*.DLL.o.* Static List of all .o files compiled conventionally for use in the standard DeskLib library. ie. <DeskLib_Sources$Dir>.Libraries.Static.*.Static.o.* <DeskLib_Sources$Dir>.Libraries.DLL.*.Static.o.* DLLClient List of all Stubs files, and all .o files from non-DLL sublibraries compiled for use in clients. ie. <DeskLib_Sources$Dir>.Libraries.DLL.*.DLL.Stubs <DeskLib_Sources$Dir>.Libraries.Static.*.Static.o.* Scripts. Some TaskObey files which do various things such as generate makefiles, run makefiles etc. NB a TaskObey file is the same as a normal obey file, except it runs in a taskwindow when double-clicked. Static+DLL. These scripts make both the static and DLL parts of DeskLib MakeAll Does everything needed to make the three DeskLib library files. MakeLibs Does all the LibFile-ing needed to completely remake DeskLib. Useful if a library is changed - just run the library's makefiles and then run this script. This saves running every makefile as done by MakeAll. CleanC Removes all C .o files. Clean Removes all .o files. MakeMFs Remakes every makefile in the sublibraries. MakeAll2 This *completely* remakes DeskLib - new makefiles, trims the DeskLib headers, deletes all .o files and recompiles etc. Commands. Some general DeskLib-specific commands. These are accessed with (for eg.) DeskLib_Commands:EachStatic ... EachStatic 'EachStatic <command>' runs <command> on every static-only DeskLib sublibrary. Any occurrence of '%0' is replaced by the complete dirname of the sublibrary, while '%1' is replaced by the leafname of the sublibrary (ie the sublibrary name). This uses 'Every' and 'IfNotExist'. EachDLL As above, except <command> is run on each DLL-sublibrary. EachLib As above, except <command> is run on all DeskLib's sublibraries, both static and DLL. EachUser As above, except <command> is run on all the libraries in '!DLUser'. Append 'Append <file> <text>' appends '|<text>' to <file> Static. All the scripts to do with making the static DeskLib DeskLib:o.DeskLib MakeAll This makes the entire static version of DeskLib, 'DeskLib:o.DeskLib'. It first runs RunStaMFs, then runs MakeLib. MakeOList Makes ObjLists.Static, a list of all .o files compiled for the static version of DeskLib MakeStaMFs Makes a makefile in each sublibrary directory. The makefile makes each .c/s file into a .o suitable for the static version of DeskLib. RunStaMFs This runs AMU on each makefile created by the above MakeStaMFs. MakeLib Runs MkOList to generate the file ObjLists.Static, and then uses LibFile to merge all .o files into DeskLib:o.DeskLib. CleanC Deletes every .Static.o.* file which was made from a .c file. Clean Deletes every .Static.o.* file. MakeAll2 This *completely* remakes the static DeskLib library - new makefiles, trims the headers, deletes all static .o files and recompiles them, and then calls LibFiles to make DeskLib:o.DeskLib . Note that the DLL DeskLib is not updated. CleanMake Deletes all static .o files and recompiles, and then remakes DeskLib:o.DeskLib . DLL. All the scripts to do with making the DLL DeskLib. CleanDLLC Deletes all .o files that came from .c files. CleanDLLOb Deletes all non .o object files - Stubs, PlainStubs, OSObj and Header. I used this when a new version of the SDLS came out. CopySObjs Copies every .o file that came from assembling a .s file in the 'Static' subdirectory, into the .o directory of the 'DLL' subdirectory. MakeAll This makes the two DLL-DeskLibs DeskLib:o.DLLDLL and DeskLib:o.DLLClient It first runs RunSubsOs, then MakeDLibs, then RunDLL, then MoveDLLs. MkDCList Generates the 'ObjLists.DLLClient' file - all DLL Stubs files plus all .o files from non-DLL sublibraries compiled for linking with *clients*. MkDDList Generates the 'ObjLists.DLLDLL' file - all DLL Stubs files plus all .o files from non-DLL sublibraries compiled for linking with *DLLs*. MakeDLibs Makes the two libraries needed for DLL client and the actual SDLS libraries. MakeTree Makes all the subdirs and makefiles for a DLL sublibrary. -- Scripts for making makefiles -- MakeDLL Uses Makatic to generate a makesfile in each DLL sublibrary directory which makes the DLL. Each makefile is based on 'TemplateMF.MakeDLL' MakeStbsOs Uses Makatic to make a makefile in each DLL sublibrary directory which makes all .o files for that library and also makes the Stubs file for that sublibrary. Each makefile is based on TemplateMF.MakeStubsOs Also makes the MakeOs makefile in each non-DLL sublibrary, whch makes all .o files suitable for linking with a DLL. MkClientOs Uses Makatic to make a makefile in each static-sublibrary. This makefile will make .o files suitable for static linking with client applications. MakeAllMFs Calls all three of the above files. -- Scripts for running makefiles -- RunClientO Runs each <libname>.DLLClient.MkClientOs makefile. RunDLL Runs the 'MakeDLL' makefiles in each DLL-library. RunStubOs Runs each of the MakeDLL makefiles. OtherLibs Scripts for making the extra libraries that aren't included in the main 'DeskLib:o.DeskLib' library (eg Debug and SmallError). MakeAll Runs amu on the makefile within each directory in '!DLSources.OtherLibs'. Clean Deletes all .o files within '!DLSources.Scripts.OtherLibs'. - Julian Smith