1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML LANG="en-US"> 3 4<HEAD> 5 <META http-equiv="Content-Type" content="text/html; charset=utf-8"> 6 <META http-equiv="Content-Style-Type" content="text/css"> 7 8 <TITLE>CTR-SDK Build System Manual (for DLLs)</TITLE> 9 10 <STYLE> 11 h1.left 12 { 13 color: #46f; 14 font-size: 100%; 15 } 16 ul.left, ul.left ul 17 { 18 margin: 0; 19 padding: 0; 20 } 21 ul.left 22 { 23 font-size: 0.8em; 24 } 25 ul.left li 26 { 27 margin: 0; 28 padding: 0; 29 margin-left: 1em; 30 line-height: 1.5em; 31 } 32 ul.left li a 33 { 34 margin: 0; 35 padding: 0; 36 } 37 38 H1 39 { 40 font-weight : bold; 41 font-size : 250%; 42 text-align : left; 43 color : #46f; 44 margin-bottom : 0px; 45 } 46 47 H2 48 { 49 font-weight : normal; 50 font-size : 180%; 51 margin : 24pt 0pt 6pt 0pt; 52 border-bottom-style : solid; 53 border-bottom-width : 1px; 54 } 55 56 H3 57 { 58 font-weight : bold; 59 font-size : 120%; 60 border-bottom-style : solid; 61 border-bottom-width : 1px; 62 width: 75%; 63 margin : 18pt 0pt 6pt 30pt; 64 } 65 66 H4 67 { 68 font-weight : bold; 69 font-size : 100%; 70 margin : 12pt 0pt 6pt 30pt; 71 } 72 73 H5 74 { 75 font-weight : bold; 76 margin : 12pt 0pt 6pt 30pt; 77 } 78 79 H6 80 { 81 font-weight : bold; 82 margin : 12pt 0pt 6pt 30pt; 83 } 84 85 DIV.date 86 { 87 text-align : right; 88 color : #46f; 89 margin-bottom : 30pt; 90 line-height : 150%; 91 } 92 93 P 94 { 95 margin : 0pt 0pt 12pt 30pt; 96 line-height : 150%; 97 } 98 99 OL,UL,DL 100 { 101 margin : 6pt 0pt 6pt 50pt; 102 } 103 OL OL, UL UL 104 { 105 margin-left: 3em; 106 } 107 108 DT 109 { 110 font-family : "Courier New", monospace; 111 margin-top : 0.3em; 112 margin-bottom : 0.3em; 113 } 114 DD 115 { 116 margin-top : 0.3em; 117 margin-bottom : 0.6em; 118 } 119 120 PRE 121 { 122 font-family : "Courier New", monospace; 123 font-weight : normal; 124 125 margin : 0pt 0pt 20pt 50pt; 126 padding : 2pt 8pt 2pt 8pt; 127 background-color : #eee; 128 129 border-style : solid; 130 border-width : 1px; 131 } 132 em 133 { 134 font-style: normal; 135 color: red; 136 } 137 TABLE 138 { 139 margin-left : 40pt; 140 margin-bottom : 20pt; 141 border-color : #aaa; 142 border-width : 1pt; 143 border-style : solid; 144 } 145 TD 146 { 147 font-style : normal; 148 padding : 2pt 4pt 2pt 4pt; 149 150 border-color : #aaa; 151 border-width : 1pt; 152 border-style : solid; 153 } 154 div.footer 155 { 156 border-color: black; 157 padding-top: 0.5em; 158 border-top-style : solid; 159 border-top-width : 1px; 160 width: 100%; 161 margin-top: 2em;; 162 } 163 div.footer span 164 { 165 color : #46f; 166 float: right; 167 } 168 table 169 { 170 border-collapse: collapse; 171 } 172 table td 173 { 174 } 175 table th 176 { 177 } 178 ul 179 { 180 margin-top: 1em; 181 margin-bottom: 1em; 182 } 183 span.sample 184 { 185 color: gray; 186 } 187 DL.history 188 { 189 margin: 1em; 190 } 191 DL.history DT 192 { 193 font-family : sans-serif; 194 font-weight : bold; 195 font-size : 0.8em; 196 margin : 0px; 197 } 198 DL.history DD 199 { 200 font-size : 0.9em; 201 margin : 0px 0px 4px 0px; 202 } 203 </STYLE> 204 <SCRIPT type="text/javascript"> 205 <!-- 206 function DeleteRule(index) 207 { 208 var ss = document.styleSheets.item(0); 209 210 if( ss.removeRule ) 211 { 212 ss.removeRule(index); 213 } 214 else 215 { 216 ss.deleteRule(index); 217 } 218 } 219 function OnClickAnchor(e, anchor) 220 { 221 window.parent.frames[1].location.hash = anchor; 222 223 if( e.preventDefault ) 224 { 225 e.preventDefault(); 226 } 227 else 228 { 229 e.returnValue = false; 230 } 231 } 232 function TravLeft(obj) 233 { 234 var ary = new Array(); 235 var index = 0; 236 237 for( var i = 0; i < obj.childNodes.length; ++i ) 238 { 239 var c = obj.childNodes.item(i); 240 241 if( c.nodeType == 1 ) 242 { 243 if( c.tagName == "H2" || c.tagName == "H3" ) 244 { 245 var a = c.childNodes.item(0); 246 var text = ""; 247 248 var anchor = "name-" + index; 249 index++; 250 251 if( a && a.tagName == "A" ) 252 { 253 text = a.innerHTML; 254 } 255 else 256 { 257 text = c.innerHTML; 258 } 259 260 ary.push([c.tagName.substr(1,1), "<a target=\"right\" href=\"?right#" + anchor + "\" onclick=\"OnClickAnchor(event, '" + anchor + "')\">" + text + "</a>"]); 261 } 262 else 263 { 264 ary = ary.concat(TravLeft(c)); 265 } 266 } 267 } 268 269 return ary; 270 } 271 function TravRight(obj) 272 { 273 var index = 0; 274 275 for( var i = 0; i < obj.childNodes.length; ++i ) 276 { 277 var c = obj.childNodes.item(i); 278 279 if( c.nodeType == 1 ) 280 { 281 if( c.tagName == "H2" || c.tagName == "H3" ) 282 { 283 var anchor = "name-" + index; 284 index++; 285 286 c.innerHTML = "<a name=\"" + anchor + "\">" + c.innerHTML + "</a>" 287 } 288 else 289 { 290 TravRight(c); 291 } 292 } 293 } 294 } 295 function OnLoad_Left() 296 { 297 var test = TravLeft(document.body); 298 var test2 = ""; 299 var level = 2; 300 301 test2 += "<h1 class='left'>" + document.title + "</h1>"; 302 test2 += "<ul class='left'>"; 303 for( var i in test ) 304 { 305 while( test[i][0] > level ) 306 { 307 level++; 308 test2 += "<ul>"; 309 } 310 while( test[i][0] < level ) 311 { 312 level--; 313 test2 += "</ul>"; 314 } 315 316 test2 += "<li>" + test[i][1]; 317 } 318 test2 += "</ul>"; 319 320 document.body.innerHTML = test2; 321 DeleteRule(0); 322 } 323 function OnLoad_Right() 324 { 325 TravRight(document.body); 326 } 327 function OnLoad_Frame() 328 { 329 var myname = location.pathname.substr(location.pathname.lastIndexOf("/") + 1); 330 331 var f = document.createElement("frameset"); 332 var l = document.createElement("frame"); 333 var r = document.createElement("frame"); 334 335 f.appendChild(l); 336 f.appendChild(r); 337 f.cols = "250,*"; 338 339 l.src = myname + "?left" + location.hash; 340 r.src = myname + "?right" + location.hash; 341 l.name = "left"; 342 r.name = "right"; 343 344 var h = document.documentElement; 345 var b = h.getElementsByTagName("body").item(0); 346 347 h.replaceChild(f, b); 348 } 349 350 351 if( ! window.opera ) 352 { 353 var search = location.search; 354 355 if( search == "?left" ) 356 { 357 window.onload = OnLoad_Left; 358 } 359 else if( search == "" ) 360 { 361 window.onload = OnLoad_Frame; 362 } 363 else if( search == "?right" ) 364 { 365 window.onload = OnLoad_Right; 366 } 367 368 if( search != "?right" ) 369 { 370 var ss = document.styleSheets.item(0); 371 372 if( ss.addRule ) 373 { 374 ss.addRule("body", "display: none", 0); 375 } 376 else 377 { 378 ss.insertRule("body {display: none}", 0); 379 } 380 } 381 } 382 //--> 383 </SCRIPT> 384</HEAD> 385 386<BODY> 387 388 389 390 391 392<H1>CTR-SDK Build System Manual (for DLLs)</H1> 393<DIV class="date">(2012/06/22)</DIV> 394 395 396 397 398 399<H2>Introduction</H2> 400 401<H3>About This Document</H3> 402<P> 403 This document provides information necessary to use the SDK build system to build CRO files and applications using CRO files. 404</P> 405<ul> 406 <li>Descriptions of added build-system variables 407 <li>Added tasks 408</ul> 409 410<P> 411 Information about the following can be found in the referenced documentation. 412</P> 413<ul> 414 <li>Information about developing your own build system:<br><i><a href="BuildSystemDevelopmentGuideForDll.html" target="_parent">Guide to Developing a Build System (for DLLs)</a></i> 415<li>Information about developing a more sophisticated build system:<br><i><a href="BuildSystemDevelopmentGuideForDllAdvanced.html" target="_parent">Guide to Developing a Build System (for High-Level DLLs)</a></i> 416</ul> 417 418<P> 419 This document assumes basic knowledge of CRO files. See the <i><a href="DllManual.html" target="_parent">DLL Manual</a></i> for a basic introduction to CRO files. 420</P> 421 422<H3>Notation Used in This Document</H3> 423<P> 424Content in shaded boxes, as shown below, indicate sample OMakefile code. 425</P> 426<pre> 427command option1 option2 428</pre> 429 430 431<H2>Added Variables</H2> 432<P> 433 The following build variables have been added for specifying and controlling CRO builds. 434</P> 435<ul> 436 <li><CODE>TARGET_MODULE</CODE> 437 <li><CODE>MODULE_LIST</CODE> 438 <li><CODE>MODULE_EXPORT_TYPE</CODE> 439 <li><CODE>MODULE_ENABLE_OFFSET</CODE> 440 <li><CODE>MODULE_ADD_DEBUG_INFO</CODE> 441</ul> 442<P> 443 These variables are described below. 444</P> 445 446<h3><CODE>TARGET_MODULE</CODE></h3> 447<P> 448 Specifies the name of the CRO module to create. It is used in place of <CODE>TARGET_PROGRAM</CODE>. Specifying a value for this variable builds the CRO file. 449</P> 450<P> 451 Sample Configuration: 452</P> 453<PRE> 454TARGET_MODULE = TestModule1 455</PRE> 456 457<h3><CODE>MODULE_LIST</CODE></h3> 458<P> 459 Specifies a list of build directories automatically referenced by the module that the current OMakefile is building. If the module being built uses undefined symbols, then the build system looks for definitions in the modules specified by <CODE>MODULE_LIST</CODE>. If the build system cannot find definitions in any module, it raises a link error in the final static module. 460</P> 461<P> 462 Sample Configuration: 463</P> 464<PRE> 465MODULE_LIST = ../App ../TestModule2 ../TestModule3 466</PRE> 467 468<h3><CODE>MODULE_EXPORT_TYPE</CODE></h3> 469<P> 470 Specifies the export type. The available values are <CODE>SYMBOL</CODE>, <CODE>INDEX</CODE>, and <CODE>OFFSET</CODE>. The default is <CODE>SYMBOL</CODE>. 471</P> 472<P> 473 The meanings of the various values are as follows. 474</P> 475<table> 476<tr><th>Specified Value <th>Description 477<tr><td><CODE>SYMBOL</CODE> <td>The export type is a name. 478<tr><td><CODE>INDEX</CODE> <td>The export type is an index. 479<tr><td><CODE>OFFSET</CODE> <td>The export type is an offset. 480</table> 481<P> 482 Sample Configuration: 483</P> 484<PRE> 485MODULE_EXPORT_TYPE = INDEX 486</PRE> 487 488 489<h3><CODE>MODULE_ENABLE_OFFSET</CODE></h3> 490<P> 491 Specifies whether to perform the build procedure required when modules reference symbols with an export type of <CODE>OFFSET</CODE>.A specific build procedure is required when referencing a symbol exported as an offset. This build procedure requires that the module referencing the symbol must be built no earlier than the module that exports it. In order to satisfy this restriction, the SDK's build system assumes that all modules will be built simultaneously. You can prevent this build procedure by setting <CODE>MODULE_ENABLE_OFFSET</CODE> to <CODE>false</CODE>. This enables you to build each module whenever you like. However, you will no longer be able to reference symbols exported as offsets. The default value is <CODE>true</CODE>. 492</P> 493<P> 494 Sample Configuration: 495</P> 496<PRE> 497MODULE_ENABLE_OFFSET = false 498</PRE> 499 500 501 502<h3><CODE>MODULE_ADD_DEBUG_INFO</CODE></h3> 503<P> 504Place the information required to debug the CRO object in the CRR object. The debugging information for the CRO object must be placed in the CRR object in order to debug the CRO source in the debugger. Setting <CODE>MODULE_ADD_DEBUG_INFO</CODE> to <CODE>true</CODE> allows debugging information to be placed in the CRR object, allowing the CRO source code to be debugged in the debugger. Setting <CODE>MODULE_ADD_DEBUG_INFO</CODE> to <CODE>false</CODE> does not allow the CRO source code to be debugged in the debugger. However, because it does not contain debugging information, CRR is smaller in size. The initial value is <CODE>true</CODE>. 505</P> 506<P> 507 Sample Configuration: 508</P> 509<PRE> 510MODULE_ADD_DEBUG_INFO = false 511</PRE> 512 513 514 515<H2>Settings Required for Build</H2> 516<P> 517 The following are required for building CRO files or an application that uses them, in addition to the requirements for creating ordinary applications. 518</P> 519<ul> 520<li>Creating Build Directories for CRO Files 521<li>Creating an OMakefile for the CRO Build 522<li>Adding Code for CRO Files to the Application's OMakefile 523<li>Storing CRO, CRS, and CRR Files in ROM-FS 524</ul> 525 526<h3>Creating Build Directories for CRO Files</h3> 527<P> 528 The SDK's build system assumes that you will create static and dynamic modules in separate directories. It also creates each dynamic module in its own directory. You must therefore create directories for building each of your dynamic modules, separate from the directory for the application itself. 529</P> 530<P> 531 For example, the <CODE>ro</CODE> sample demo has the following directory structure. 532</P> 533<PRE> 534Parent Directory ┬ Application Build Directory 535 │ ├ Source of static module 536 │ └ OMakefile 537 ├ Build directory of dynamic module 1 538 │ ├ Source of dynamic module 1 539 │ └ OMakefile 540 ├ Build directory of dynamic module 2 541 │ ├ Source of dynamic module 2 542 │ └ OMakefile 543 … 544 ├ Build directory of dynamic module N 545 │ ├ Source of dynamic module N 546 │ └ OMakefile 547 └ OMakefile 548</PRE> 549<P> 550 You must specify each of these build directories in <CODE>SUBDIRS</CODE> to target them for the build. 551</P> 552 553 554<h3>Creating an OMakefile for the CRO Build</h3> 555<P> 556 You must create an OMakefile with the settings for building CRO files in each CRO build directory. The minimum required contents of the OMakefile for creating CRO files are as follows. 557</P> 558<PRE> 559TARGET_MODULE = <span class="sample">Module1</span> 560MODULE_LIST = <span class="sample">../App ../Module2</span> 561SOURCES = <span class="sample">module.cpp</span> 562 563include $(ROOT_OMAKE)/modulerules 564 565build: $(DEFAULT_TARGETS) 566</PRE> 567<P> 568Change the variables above as required to configure your CRO build. Also change the <CODE>TARGET_MODULE</CODE>, <CODE>MODULE_LIST</CODE>, and <CODE>SOURCES</CODE> settings in accordance with your project. 569</P> 570<P> 571<STRONG>Note:</STRONG> The value of <CODE>TARGET_MODULE</CODE> must match the directory name. Also, do not include the target module (<CODE>Module1</CODE> in the example above) in <CODE>MODULE_LIST</CODE>. 572</P> 573 574<h3>Adding Code for CRO Files to the Application's OMakefile</h3> 575<P> 576 Specify an appropriate value for the <CODE>MODULE_LIST</CODE> variable in the application's OMakefile. Ordinarily, you should specify all the dynamic modules that the application uses. 577</P> 578<PRE> 579MODULE_LIST = ../Module1 ../Module2 580</PRE> 581<P> 582 This setting causes the CRS and CRR files to be created in <CODE>images</CODE>. 583</P> 584 585<h3>Storing CRO, CRS, and CRR Files in ROM-FS</h3> 586<P> 587 The settings above generated CRO, CRS, and CRR files, so you must now store the generated files in ROM-FS. You can store CRO and CRS files in ROM-FS in any format you want, including compressed and archive formats. In contrast, there are strong restrictions on storing the CRR file. You must store it directly below a <CODE>.crr</CODE> directory that is directly under the ROM-FS root, without changing it in any way. The <CODE>.crr</CODE> directory must not contain any files other than the CRR file. 588</P> 589<P> 590 If you automate this process using <CODE>OMake</CODE>, the application's OMakefile must include code similar to the following example. 591</P> 592<PRE> 593MODULE_NAMES = <span class="sample">Module1 Module2</span> 594MODULES_ROOT = <span class="sample">../</span> 595 596MODULE_CRO = <span class="sample">$(addprefix $(ROMFS_ROOT)/,$(addsuffix .cro,$(MODULE_NAMES)))</span> 597STATIC_CRS = <span class="sample">$(ROMFS_ROOT)/static.crs</span> 598STATIC_CRR = <span class="sample">$(ROMFS_ROOT)/.crr/static.crr</span> 599ROMFS_DEPENDENCIES = $(MODULE_CRO) $`(STATIC_CRS) $`(STATIC_CRR) 600 601foreach(TARGET, $(BUILDER.getTargets $(SUPPORTED_TARGETS))) 602 foreach(module, $(MODULE_NAMES)) 603 src = $(file $(TARGET.getImageDirectoryOf $(MODULES_ROOT)$(module))/$(module).cro) 604 dst = $(addprefix $(ROMFS_ROOT)/,$(addsuffix .cro,$(module))) 605 606 $(dst) : $(src) 607 cp $< $@ 608 609 $(STATIC_CRS): $(TARGET.getImageDirectory false)/$(TARGET_PROGRAM).crs 610 cp $< $@ 611 612 $(STATIC_CRR): $(TARGET.getImageDirectory false)/$(TARGET_PROGRAM).crr 613 mkdir -p $(dirname $@) 614 cp $< $@ 615</PRE> 616<P> 617 You must change the values of variables between <CODE>MODULE_NAMES</CODE> and <CODE>STATIC_CRR</CODE> (inclusive) to appropriate values for your project. The example above assumes that <CODE>TARGET_PROGRAM</CODE> and <CODE>ROMFS_ROOT</CODE> are configured appropriately elsewhere. 618</P> 619 620 621 622 623 624 625 626<H2>Revision History</H2> 627<dl class="history"> 628 <dt>2012/06/22</dt> 629 <dd> 630Added a link to <I>Guide to Developing a Build System (for High-Level DLLs)</I>.<br/> 631 </dd> 632 633 <dt>2011/09/26</dt> 634 <dd> 635 Added description of <CODE>MODULE_ADD_DEBUG_INFO</CODE> to <B>Added Variables</B>.<br> Added the Revision History section. 636 </dd> 637 638 <dt>2011/08/03</dt> 639 <dd> 640 Initial version. 641 </dd> 642</dl> 643 644 645<div class="footer"><span>CTR-SDK Build System Manual (for DLLs)</span></div> 646 647<p>CTR-06-0202-002-H<br>CONFIDENTIAL</p></body> 648</HTML>