Changeset 251

Show
Ignore:
Timestamp:
04/01/07 08:29:46 (1 year ago)
Author:
aldacron
Message:

[Docs]
* build.html and derelictify.html were out of date

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/docs/build.html

    r233 r251  
    1111<hr> 
    1212<h3>Introduction</h3> 
    13 In the top-level Derelict directory ($DERELICT_HOME) you will find a D module  
    14 named <tt>buildme.d</tt>. It can, and is intended to, be run as a script. Executing 
    15 this file will create one or more libraries from the Derelict packages. At the 
    16 end of execution, all of the libraries that were created will be found in the 
    17 $DERELICT_HOME/lib directory. 
     13While it is possible to compile any or all of the Derelict packages into static 
     14libraries, it is not recommended that you do so. The provided build script exists 
     15solely as a convenience for those who absolutely need it. The recommended way of 
     16using Derelict in your applications is to make use of a build tool, such as 
     17<a href="http://www.dsource.org/projects/build">Bud</a> or 
     18<a href="http://www.dsource.org/projects/dsss/wiki/Rebuild">Rebuild</a>. Given 
     19a single D source module, these tools can automatically compile and link all 
     20imported modules to create an executable. So unless you absolutely must use the 
     21static libraries, please consider using the recommended approach instead. 
     22<p> 
     23For those who do need the libraries, in the top-level Derelict directory 
     24($DERELICT_HOME) you will find a D module named <tt>buildme.d</tt>. It can be, 
     25and is intended to be, run as a script. Executing this file will create one or 
     26more libraries from the Derelict packages. At the end of execution, all of the 
     27libraries that were created will be found in the $DERELICT_HOME/lib directory. 
     28</p> 
    1829 
    19 <div class="note">You may be tempted to compile buildme.d into an executable. It 
    20 is strongly recommended that you do not. The script is intended to be run from 
    21 the command line of a console window, as a script, so that you may see any  
    22 error text that is output. Should you compile an executable and launch from the 
    23 desktop, or any other non-console window, you will not see the error text.</div> 
     30<div class="important">Derelict has built-in support for  
     31<a href="http://www.dsource.org/projects/tango">Tango</a>. but currently the 
     32build script cannot be executed in a Tango-enabled environment. If you need to 
     33use Derelict with Tango, you must do so using the method recommended above (with 
     34Bud or Rebuild).</div> 
     35 
     36<h3>Requirements</h3> 
     37Currently, the build script requires that <a href="http://www.dsource.org/projects/build"> 
     38Bud</a> be on your PATH. If it is not, the script will fail. 
     39 
     40<h3>Execution</h3> 
     41To execute the build script, cd to $DERELICT_HOME and use one of the following 
     42command lines: 
     43 
     44<pre> 
     45    dmd -run buildme.d 
     46    gdmd -run buildme.d 
     47</pre> 
     48 
     49The first is the command line to use with DMD. The second is for GDC. In the rest 
     50of this document, 'dmd' will be used for example command lines. Anytime you see 
     51'dmd', you can replace it with 'gdmd' to use the same command line with GDC. 
    2452 
    2553<h3>Options</h3> 
    2654Before executing the build script, you need to decide which libraries you want 
    2755to build and how you want to build them. There are a few command line options 
    28 you can pass along. When reading the options below, keep in mind that they 
    29 can be specified in any order. 
    30  
    31 <h4>Which Compiler?</h4> 
    32 <p><div class="important"> 
    33 This section is currently incorrect. For the time being, the build script requires 
    34 you to have the <a href="#bud">Bud utility</a> installed. No other build tools or 
    35 compilers are supported. The instructions to execute the script are valid, you just 
    36 have only one option. This will change eventually and this section will be updated 
    37 at that time. 
    38 </div></p> 
    39  
    40 <p> 
    41 The script supports compiling directly 
    42 with DMD and GDC (gdmd), or indirectly with <a href="#bud">Derek Parnell's Bud</a>. Executing the script  
    43 with no arguments will compile all libraries with the compiler used to execute  
    44 the script: 
    45  
    46 <pre> 
    47     cd $DERELICT_HOME 
    48     dmd -run buildme.d  <-- This will compile with DMD 
    49     gdmd -run buildme.d <-- This will compile with GDC 
    50 </pre> 
    51  
    52 If you have Bud installed, you can use it to build the libraries by passing 
    53 "bud" on the command line: 
    54  
    55 <pre> 
    56     cd $DERELICT_HOME 
    57     dmd -run buildme.d bud 
    58 </pre> 
    59  
    60 This should work whether you execute the script with dmd or gdmd. Bud will 
    61 use the compiler for which it is configured. 
    62 </p> 
     56you can pass along. With the exception of the 'cleanlib' option, all options 
     57may be passed in any order. 
    6358 
    6459<h4>Debug or Release?</h4> 
    …… 
    6762 
    6863<pre> 
    69     cd $DERELICT_HOME 
    7064    dmd -run buildme.d debug 
    7165</pre> 
    …… 
    7367The script also accepts 'release' as a command line argument. 
    7468 
    75 <p> 
    76 If you are using Bud, you can find the configuration options in the following 
    77 files: 
    78 </p> 
     69<h4>Options for Bud</h4> 
     70 
     71The build script generates a temporary Bud Response File that is deleted at the 
     72end of execution. Sometimes, when debugging problems with the build script, it 
     73is necessary to see the contents of this file. You can prevent the script from 
     74deleting the file by passing 'nodelbrf' on the command line: 
    7975 
    8076<pre> 
    81 $(DERELICT_HOME)/build_common.txt 
    82 $(DERELICT_HOME)/build_release.txt 
    83 $(DERELICT_HOME)/build_debug.txt 
     77    dmd -run buildme.d nodelbrf 
    8478</pre> 
    8579 
    86  
    87 <tt>build_common.txt</tt>, <tt>build_debug.txt</tt>, and <tt>build_release.txt</tt> 
    88 may all be edited to your preference. The rules for editing these files are the 
    89 same as those for editing <a href="http://build.dsource.org/response_file.html">Bud 
    90 Response Files</a>, but there are some caveats. Because <tt>buildme.d</tt> automates 
    91 the build process, some assumptions are made. The first is that the output directory 
    92 will be the <tt>$DERELICT_HOME/lib</tt> subdirectory. Adding -TsomeDir to any of 
    93 the three files will have no effect. Second, the import paths for building each 
    94 package are set automatically. Third, the DerelictUtil package and other dependencies 
    95 are excluded from the compilation automatically via the -X Bud option, so you 
    96 need not do so yourself. 
    97  
    98  
    99 <p> 
    100 If you are not using Bud, you can find configuration options in the script itself. 
    101 The following variables are what you should look for: 
    102 </p> 
     80You can also pass options to both Bud and the compiler, though not via the command 
     81line. This is done through the following three options files: 
    10382 
    10483<pre> 
    105 COMPILE_FLAGS_DEBUG 
    106 COMPILE_FLAGS_RELEASE 
    107 COMPILE_FLAGS_COMMON 
     84$(DERELICT_HOME)/buildopts/bud_common.txt 
     85$(DERELICT_HOME)/buildopts/bud_release.txt 
     86$(DERELICT_HOME)/buildopts/bud_debug.txt 
    10887</pre> 
    10988 
    110 The options in COMPILE_FLAGS_COMMON are used in both Debug and Release builds. 
    111  
    112 For most users, there is no need to edit any of the options. But feel free to 
    113 do so if you need to. 
     89Options in <tt>bud_common.txt</tt> are used in both Debug and Release builds. The other 
     90two are self-explanatory. 
     91<p> 
     92The rules for editing these files are the same as those for editing 
     93<a href="http://build.dsource.org/response_file.html">Bud Response Files</a>, 
     94but there are some caveats. Because <tt>buildme.d</tt> automates the build process, 
     95some assumptions are made. The first is that the output directory will be the 
     96<tt>$DERELICT_HOME/lib</tt> subdirectory. Adding -TsomeDir to any of the three 
     97files will have no effect. Second, the import paths for building each package 
     98are set automatically so that you don't need to. Third, the DerelictUtil package 
     99and other dependencies are excluded from the compilation automatically via the 
     100-X Bud option (except, of course, when DerelictUtil itself is being compiled). 
     101</p><p> 
     102For most users, the default configuration should suffice. 
     103</p> 
    114104 
    115105<h4>Which Packages?</h4> 
    …… 
    133123</pre> 
    134124 
    135 This will delete the libraries in $(DERELICT_HOME/lib). Unlike the other command  
    136 line options, this option must be specified first. Any options following it will  
     125This will delete the libraries in $(DERELICT_HOME/lib). Unlike the other command 
     126line options, this option must be specified first. Any options following it will 
    137127be ignored. If it is not first, it will be ignored. 
    138128 
    139 <div class=Note> 
    140 On windows, executing the cleanlib option with DMD will cause the script to delete 
    141 files with the .lib extension, while doing so with GDC (gdmd) will cause the 
    142 script to delete files with the .a extension. 
    143 </div> 
     129<h3>Troubleshooting</h3> 
     130If you have any problems building Derelict with Bud, you may direct them to the 
     131<a href="http://www.dsource.org/forums/viewforum.php?f=19&sid=d6f86cfb804d7c8727af1f58cd327d2c">Derelict Forums</a> 
     132and someone will try to help you. Please don't post problems on the Bud forums 
     133unless you are absolutely certain the problem is with Bud and not with Derelict. 
    144134 
    145 <a name="bud"><h3>Derelict Parnell's Bud</h3></a> 
    146 Bud, created and maintained by Derek Parnell, is an incredibly 
    147 useful tool. Feed it one D source module on the command line and it will automatically 
    148 spit out a library or an executable. It follows the import tree, and passes 
    149 each imported module to the D compiler and linker or librarian. Several command 
    150 line options can give you fine-tuned control over how the compilation process 
    151 goes. You can put special pragmas directly in your code to further control how 
    152 Bud processes your source modules. 
    153 <p> 
    154 Bud entirely eliminates the need for Makefiles. If you have ever maintained 
    155 project Makefiles for multiple platforms, you will appreciate what that means. 
    156 Replacing Derelict's old Makefiles with a build system designed around Bud 
    157 has had an amazing impact on package maintenance. If you want to compile Derelict 
    158 out of the box, separate from your project, you will need to have Bud installed. 
    159 Anyone who insists on maintaining their own Makefiles instead is free to do so -  
    160 just don't bother submitting them to the Derelict maintainers. 
    161 </p> 
    162  
    163 <h4>Getting Your Hands on Bud</h4> 
    164 The latest version of Bud may always be found at the 
    165 <a href="http://www.dsource.org/projects/build"> 
    166 Build Project Home Page</a>. You can read about the latest changes in the 
    167 <a href="http://www.dsource.org/forums/viewforum.php?f=52">Bud Forum</a> 
    168 (always the first post in the thread titled "Release Announcements" at the top 
    169 of the topic list). 
    170  
    171  
    172 <h3>Troubleshooting</h3> 
    173 If you have any problems building Derelict with the Bud, you may direct 
    174 them to the  
    175 <a href="http://www.dsource.org/forums/viewforum.php?f=19&sid=d6f86cfb804d7c8727af1f58cd327d2c">Derelict Forums</a> 
    176 and someone will try to help you. Please don't post problems on the Build forums 
    177 unless you are absolutely certain the problem is with Build and not Derelict's 
    178 scripts. 
    179135</body> 
    180136</html> 

  • trunk/docs/derelictify.html

    r203 r251  
    1818<p> 
    1919Bugfixes and enhancements to existing code or documentation will almost always 
    20 be folded in. New packages, however, often will not be. If we were to accept  
    21 any and all packages submitted, Derelict would quickly become bloated, unwieldy,  
     20be folded in. New packages, however, often will not be. If we were to accept 
     21any and all packages submitted, Derelict would quickly become bloated, unwieldy, 
    2222and difficult to maintain. New packages will most definitely be added over time, 
    23 but they must meet some loose criteria, as explained on the  
     23but they must meet some loose criteria, as explained on the 
    2424<a href="index_a.html#criteria">front page</a>. 
    2525</p><p> 
    26 Whether you are making a package for inclusion in the trunk, distributing it  
    27 separately, or using it privately, there are a few guidelines that should be  
     26Whether you are making a package for inclusion in the trunk, distributing it 
     27separately, or using it privately, there are a few guidelines that should be 
    2828followed when creating the package. 
    2929</p> 
    …… 
    3131<h3>The Bindings</h3> 
    3232At a very minimum, the bindings you create must be designed to allow manual loading 
    33 of a shared library. If the library to which you are binding cannot be compiled  
    34 in shared library form, then the binding cannot be Derelictified. Creating a  
     33of a shared library. If the library to which you are binding cannot be compiled 
     34in shared library form, then the binding cannot be Derelictified. Creating a 
    3535shared library binding involves several steps, which this document attempts to 
    3636clarify. 
    …… 
    3838<h4>typedefs, constants and #defined values</h4> 
    3939C typedefs can translate to either alias or typedef statements. Derelict 
    40 modules should use the alias form. Constants must be declared as publicly available 
    41 const variables at the module scope (meaning, they should not be wrapped in  
    42 structs or classes). #defined values, depending on the intention, should either 
    43 be declared as aliases or publicly available const variables at the module 
    44 scope. 
     40modules should use the alias form. Constants should be declared in anonymous 
     41enums. #defined values, depending on the intention, should either 
     42be declared as aliases or anonymous enums. 
     43 
     44<div class="note">Derelict packages originally declared constants as publicly 
     45available constant values. In order to help reduce the size of the resultant 
     46binaries, a process was begun to convert all such values to anonymous enums. 
     47Currently, the conversion is not complete so you will see examples of both usages 
     48in the packages. New packages should all use the enum form. Example: 
     49 
     50<pre> 
     51enum 
     52{ 
     53    CONSTANT_ONE    = 10, 
     54    CONSTANT_TWO    = 22, 
     55    CONSTANT_THREE  = 25, 
     56} 
     57</pre> 
     58</div> 
     59 
    4560<p> 
    4661Where to put these declarations depends entirely upon the size of the library 
    …… 
    4863that all types are declared in context-specific modules along with function 
    4964declarations and converted macros. Because of the number of headers in SDL, this 
    50 approach makes sense. DerelictAL (and most of the other Derelict packages), on  
    51 the other hand, declares all types in a special types module, while functions  
     65approach makes sense. DerelictAL (and most of the other Derelict packages), on 
     66the other hand, declares all types in a special types module, while functions 
    5267are declared separately. Generally, this is the approach you should take when 
    5368the size of the binding is not so large to make this approach difficult to 
    …… 
    6782All Derelict packages must provide function pointer declarations. When a shared 
    6883library is manually loaded, the function pointers will be initialized to point 
    69 to the proper memory locations in the shared library's address space. The  
    70 declarations of the function pointers should be typedefed and should have the  
     84to the proper memory locations in the shared library's address space. The 
     85declarations of the function pointers should be typedefed and should have the 
    7186following syntax: 
    7287</p> 
    …… 
    88103<p> 
    89104Following the function declarations should be global variables of the type 
    90 <span class="bold">pfFunctionName</span> (for each function), and named  
     105<span class="bold">pfFunctionName</span> (for each function), and named 
    91106<span class="bold">FunctionName</span>. Expanding the above example: 
    92107</p> 
    …… 
    94109<pre> 
    95110typedef void function(int) pfMyFunction; 
    96 typedef int function() pfMyOtherFunction;  
     111typedef int function() pfMyOtherFunction; 
    97112typedef int function(float, char*, void*) pfyetAnotherMyFunction; 
    98113pfMyFunction            MyFunction;                 // pointer to C function named MyFunction 
    …… 
    112127<pre> 
    113128typedef void function(int) pfMyFunction; 
    114 typedef int function() prMyOtherFunction;  
     129typedef int function() prMyOtherFunction; 
    115130typedef int function(float, char*, void*) pfyetAnotherMyFunction; 
    116131pfMyFunction            MyFunction; 
    …… 
    136151 
    137152<p> 
    138 The binding of a function is done via the <span class="bold">bindFunc</span>  
    139 template. First, you must implement a function that will handle all of the  
    140 loading. This function should be private to your module. The function should  
     153The binding of a function is done via the <span class="bold">bindFunc</span> 
     154template. First, you must implement a function that will handle all of the 
     155loading. This function should be private to your module. The function should 
    141156accept a <span class="bold">SharedLib</span> as the only argument. 
    142157</p> 
    …… 
    145160private void loadFoo(SharedLib lib) 
    146161{ 
    147      
    148 } 
    149 </pre> 
    150  
    151 <p> 
    152 If you are unfamiliar with the mechanics of D templates, the call syntax of  
    153 <span class="bold">bindFunc</span> may be quite strange to you. In this case,  
    154 there are two sets of parantheses. In the first set of parentheses, you need to  
     162 
     163} 
     164</pre> 
     165 
     166<p> 
     167If you are unfamiliar with the mechanics of D templates, the call syntax of 
     168<span class="bold">bindFunc</span> may be quite strange to you. In this case, 
     169there are two sets of parantheses. In the first set of parentheses, you need to 
    155170pass the function pointer to which you are binding the function. The second set of 
    156171parentheses is where, in this particluar case, you provide the arguments to an 
    157172<span class="bold">opCall</span> implementation internal to 
    158173<span class="bold">bindFunc</span>. Here, you should pass the name of the 
    159 function as a string and the <span class="bold">SharedLib</span> reference  
     174function as a string and the <span class="bold">SharedLib</span> reference 
    160175passed to your load function. It's easier to understand seeing it in action than 
    161176reading a description of it. The following example expands on the previous 
    …… 
    167182 
    168183typedef void function(int) pfMyFunction; 
    169 typedef int function() prMyOtherFunction;  
     184typedef int function() prMyOtherFunction; 
    170185typedef int function(float, char*, void*) pfyetAnotherMyFunction; 
    171186pfMyFunction            MyFunction; 
    …… 
    176191typedef double function(int) pfAnotherFooFunction; 
    177192pfFooFunction           FooFunction; 
    178 pfAnotherFooFunction    AnotherFooFunction;  
     193pfAnotherFooFunction    AnotherFooFunction; 
    179194 
    180195private void loadFoo(SharedLib lib) 
    …… 
    193208method: 
    194209 
    195 <p class="bold">GenericLoader.setup(char[] windowsNames, char[] linuxName,  
    196 char[] macNames, void function(SharedLib) loadFunc)</p>  
     210<p class="bold">GenericLoader.setup(char[] windowsNames, char[] linuxName, 
     211char[] macNames, void function(SharedLib) loadFunc)</p> 
    197212 
    198213<p>Each of the name parameters are either a single library name or a comma-separated 
    …… 
    200215when the <span class="bold">load</span> method is called with no arguments. When 
    201216multiple names are supplied, they will be loaded in the order given. As an example, 
    202 here is the implementation for DerelictAL:  
     217here is the implementation for DerelictAL: 
    203218</p> 
    204219<pre> 
    205220GenericLoader DerelictAL; 
    206 static this()  
     221static this() 
    207222{ 
    208223    DerelictAL.setup( 
    …… 
    240255<h4>Use the Source, Luke</h4> 
    241256If you find this documentation confusing (I do, and I wrote it), then the source 
    242 is your best recourse. It's fairly self-explanatory. I recommend that you use  
     257is your best recourse. It's fairly self-explanatory. I recommend that you use 
    243258DerelictAL and DerelictSDL as examples, for consistency. 
    244259</body>