home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / amigalib / d982 / bin2hunk.lha / Bin2Hunk / Bin2Hunk.Doc < prev    next >
Encoding:
Text File  |  1994-04-04  |  5.4 KB  |  148 lines
  1. ***************************************************************************
  2. *                                                                         *
  3. *                                Bin2Hunk V2.2                            *
  4. *                                                                         *
  5. *                          © 1993 by Brian Koetting                       *
  6. *                                                                         *
  7. ***************************************************************************
  8.  
  9.  
  10. ** DISTRIBUTION:***********************************************************
  11.  
  12. Bin2Hunk is FREELY redistributable.  With the exception of reasonable media
  13. and distribution costs, no one should be making money off this.
  14.  
  15. ** AAD:********************************************************************
  16.  
  17. Please add ALL APPLICABLE DISCLAIMERS here.
  18.  
  19. ** INTRODUCTION:***********************************************************
  20.  
  21. As the name implies, this program will convert any binary file to an
  22. AmigaDOS hunk (or object file) that can be linked with your linker into
  23. your program.
  24.  
  25. This is most useful when you wish some form of data to be a part of your
  26. executable.  This data can be sound samples, images, text, or whatever.
  27.  
  28. At least one other program of this genre is available, but the one I am
  29. aware of, did not even work properly, was CLI-based only, and about 20K.
  30.  
  31. Bin2Hunk, however, sports a ReadArgs() CLI-interface, a GadTools
  32. Intuition interface, and weighs-in around 6K!  Bin2Hunk also boasts the
  33. ASL file requester and also asks for confirmation before overwriting
  34. an already existing file.  So what are you waiting for?
  35.  
  36. Bin2Hunk is "Enforcer" and "Mungwall" passed, and tested with the SAS/C
  37. compiler Versions 5.10 through 6.51.
  38.  
  39. ** USAGE:******************************************************************
  40.  
  41. Bin2Hunk runs only under AmigaDOS 2.0 and above.
  42.  
  43. Bin2Hunk accepts the following command line argument:
  44.  
  45.     Bin2Hunk InFile/A,OutFile,NAME/K,LENGTH/K,HUNK/K,CHIP/S,FAST/S:
  46.  
  47. where:
  48.  
  49. -    InFile is the name (and path) of your binary file to convert.
  50.  
  51. -    OutFile is the name (and path) of the final hunk object file.
  52.  
  53. -    NAME=<string> is the name of the data array that will be used as
  54.     the external reference. (the name by which you want to access the
  55.     data)
  56.  
  57. -    LENGTH=<string> is the name of an optional external reference to
  58.     the size of your data.  This 32-bit value (LONG) will be in bytes.
  59.  
  60. -    HUNK=<string> is the name of the new hunk.  See below for details.
  61.  
  62. -    CHIP will ensure that your data will be loaded into CHIP ram.
  63.  
  64. -    FAST will ensure that your data will be loaded into FAST ram.
  65.  
  66. When you specify an InFile, Bin2Hunk also creates default names for the
  67. remaining strings with the following rules:
  68.  
  69. -    OutFile becomes the base name of InFile but with an .o appended.
  70.  
  71. -    Data Name becomes the base name of InFile with an "_" prepended.
  72.     This is useful for C programmers.
  73.  
  74. -    Length Name is the base name of InFile with an "_" prepended and
  75.     "_len" appended.
  76.  
  77. When other names are specified, the default ones are overwritten.  Note
  78. that Bin2Hunk will allow names that AmigaDOS and/or your compliler/
  79. assembler will not accept.  Please be careful with your names.
  80.  
  81. Most C compilers require an underscore ("_") prepended to the varible,
  82. since they also do this themselves.  In other words, if you want to
  83. access the data with the name "foo_data", then you need to supply
  84. Bin2Hunk with the name "_foo_data".  Assemblers do not do this however.
  85.  
  86. The Hunk name is used by the linker to merge hunks.  Any hunks with the
  87. same name are merged together.  A blank name is a valid hunk name.
  88. If you do not use the __MERGED hunk name, you may have to declare
  89. your external data reference item with the "__far" keyword (assuming
  90. you're using a SAS/C compiler).
  91.  
  92. Typically your external declaration should look like this:
  93.  
  94. For Memory Type of ANY:
  95.     extern UBYTE data_ptr[];
  96.  
  97. For Memory Type of CHIP:
  98.     extern UBYTE __chip data_ptr[];
  99.  
  100. For Memory Type of FAST:
  101.     extern UBYTE __far data_ptr[];
  102.  
  103. You may have to experiment using the __far and __chip keywords, or your
  104. compilers equivalents.  Please consult your compiler's manual for more
  105. information.
  106.  
  107. If no InFile is specified, Bin2Hunk will open it's interface window.
  108.  
  109. The interface window contains gadgets for all these options and operates
  110. in a self-explanitory manner.
  111.  
  112. ** WHAT IT DOES:***********************************************************
  113.  
  114. Basically, Bin2Hunk takes your file and copies it into an AmigaDOS hunk
  115. file in the following format:
  116.  
  117. HUNK_UNIT
  118. HUNK_NAME <your hunk name>
  119. HUNK_DATA <your data>
  120. HUNK_EXT  <external reference to your data and a variable of its length>
  121. HUNK_END
  122.  
  123. as detailed in the Bantam AmigaDOS Manual 3rd Edition Chapter 10.
  124.  
  125. ** CREDITS, COMMENTS, REQUESTS, BUGS, DONATIONS:***************************
  126.  
  127.     Brian Koetting can be reached through:
  128.  
  129.     BIX: bsk
  130.     EMAIL: koettingb@yvax.byu.edu
  131.  
  132.     MAIL:
  133.     671 East 420 North
  134.     Provo, Utah 84606
  135.  
  136. ** HISTORY:****************************************************************
  137.  
  138. V1.4 First public release
  139. V1.5 Added ASL file requester for SAVE function
  140. V1.6 Fixed bug with "Memory Type" due to error in AmigaDOS manual
  141. V1.7 Made window adjust to different Screen fonts.  (still uses topaz,
  142.      but now adjusts the window to account for a differnt size title bar)
  143. V2.0 Added HUNK_NAME support - now accepts (and saves) a name for the hunk
  144. V2.1 Added LAmiga-Q to quit
  145. V2.2 Fixed minor bug
  146.  
  147. ***************************************************************************
  148.