prog.tex 222 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957
  1. %
  2. % $Id$
  3. % This file is part of the FPC documentation.
  4. % Copyright (C) 1997, by Michael Van Canneyt
  5. %
  6. % The FPC documentation is free text; you can redistribute it and/or
  7. % modify it under the terms of the GNU Library General Public License as
  8. % published by the Free Software Foundation; either version 2 of the
  9. % License, or (at your option) any later version.
  10. %
  11. % The FPC Documentation is distributed in the hope that it will be useful,
  12. % but WITHOUT ANY WARRANTY; without even the implied warranty of
  13. % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  14. % Library General Public License for more details.
  15. %
  16. % You should have received a copy of the GNU Library General Public
  17. % License along with the FPC documentation; see the file COPYING.LIB. If not,
  18. % write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19. % Boston, MA 02111-1307, USA.
  20. %
  21. \documentclass{report}
  22. %
  23. % Preamble
  24. %
  25. \ifx\pdfoutput\undefined
  26. \usepackage{html}
  27. \usepackage{htmllist}
  28. \latex{\usepackage{fpc}}
  29. \else
  30. \usepackage{fpc}
  31. \fi
  32. %
  33. \html{\input{fpc-html.tex}}
  34. %
  35. \ifpdf
  36. \pdfinfo{/Author(Michael Van Canneyt)
  37. /Title(Programmers' Guide)
  38. /Subject(Free Pascal Programmers' guide)
  39. /Keywords(Free Pascal)
  40. }
  41. \fi
  42. %
  43. % Settings
  44. %
  45. \makeindex
  46. \FPCexampledir{progex}
  47. %
  48. % Start of document.
  49. %
  50. \begin{document}
  51. \title{Free Pascal \\ Programmers' manual}
  52. \docdescription{Programmers' manual for \fpc, version \fpcversion}
  53. \docversion{1.8}
  54. \input{date.inc}
  55. \author{Micha\"el Van Canneyt}
  56. \maketitle
  57. \tableofcontents
  58. \newpage
  59. \listoftables
  60. \newpage
  61. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  62. % Introduction
  63. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  64. \section*{About this document}
  65. This is the programmer's manual for \fpc.
  66. It describes some of the peculiarities of the \fpc compiler, and provides a
  67. glimpse of how the compiler generates its code, and how you can change the
  68. generated code. It will not, however, provide you with a detailed account of
  69. the inner workings of the compiler, nor will it tell you how to use the
  70. compiler (described in the \userref). It also will not describe the inner
  71. workings of the Run-Time Library (RTL). The best way to learn about the way
  72. the RTL is implemented is from the sources themselves.
  73. The things described here are useful if you want to do things which need
  74. greater flexibility than the standard Pascal language constructs
  75. (described in the \refref).
  76. Since the compiler is continuously under development, this document may get
  77. out of date. Wherever possible, the information in this manual will be
  78. updated. If you find something which isn't correct, or you think something
  79. is missing, feel free to contact me\footnote{at
  80. \var{[email protected]}}.
  81. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  82. % Compiler switches
  83. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  84. \chapter{Compiler directives}
  85. \label{ch:CompSwitch}
  86. \fpc supports compiler directives in your source file. They are not the same
  87. as Turbo Pascal directives, although some are supported for compatibility.
  88. There is a distinction between local and global directives; local directives
  89. take effect from the moment they are encountered, global directives have an
  90. effect on all of the compiled code.
  91. Many switches have a long form also. If they do, then the name of the
  92. long form is given also. For long switches, the + or - character to switch
  93. the option on or off, may be replaced by \var{ON} or \var{OFF} keywords.
  94. Thus \verb|{$I+}| is equivalent to \verb|{$IOCHECKS ON}| or
  95. \verb|{$IOCHECKS +}| and
  96. \verb|{$C-}| is equivalent to \verb|{$ASSERTIONS OFF}| or
  97. \verb|{$ASSERTIONS -}|
  98. The long forms of the switches are the same as their Delphi
  99. counterparts.
  100. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  101. % Local switches
  102. \section{Local directives}
  103. \label{se:LocalSwitch}
  104. Local directives can occur more than once in a unit or program,
  105. If they have a command-line counterpart, the command-line artgument is
  106. restored as the default for each compiled file. The local directives
  107. influence the compiler's behaviour from the moment they're encountered
  108. until the moment another switch annihilates their behaviour, or the end
  109. of the current unit or program is reached.
  110. \subsection{\var{\$A} or \var{\$ALIGN}: Align Data}
  111. This switch is recognized for Turbo Pascal Compatibility, but is not
  112. yet implemented. The alignment of data will be different in any case, since
  113. \fpc is a 32-bit compiler.
  114. \subsection{\var{\$ASMMODE} : Assembler mode}
  115. \label{se:AsmReader}
  116. The \var{\{\$ASMMODE XXX\}} directive informs the compiler what kind of assembler
  117. it can expect in an \var{asm} block. The \var{XXX} should be replaced by one
  118. of the following:
  119. \begin{description}
  120. \item [att\ ] Indicates that \var{asm} blocks contain AT\&T syntax assembler.
  121. \item [intel\ ] Indicates that \var{asm} blocks contain Intel syntax
  122. assembler.
  123. \item [direct\ ] Tells the compiler that asm blocks should be copied
  124. directly to the assembler file.
  125. \end{description}
  126. These switches are local, and retain their value to the end of the unit that
  127. is compiled, unless they are replaced by another directive of the same type.
  128. The command-line switch that corresponds to this switch is \var{-R}.
  129. The default assembler reader is the AT\&T reader.
  130. \subsection{\var{\$B} or \var{\$BOOLEVAL}: Complete boolean evaluation}
  131. This switch is understood by the \fpc compiler, but is ignored. The compiler
  132. always uses shortcut evaluation, i.e. the evaluation of a boolean expression
  133. is stopped once the result of the total exression is known with certainty.
  134. So, in the following example, the function \var{Bofu}, which has a boolean
  135. result, will never get called.
  136. \begin{verbatim}
  137. If False and Bofu then
  138. ...
  139. \end{verbatim}
  140. This has as a consequence that any additional actions that are done by
  141. \var{Bofu} are not executed.
  142. \subsection{\var{\$C} or \var{\$ASSERTIONS} : Assertion support}
  143. The \var{\{\$ASSERTION\}} switch determines if assert statements are
  144. compiled into the binary or not. If the switch is on, the statement
  145. \begin{verbatim}
  146. Assert(BooleanExpression,AssertMessage);
  147. \end{verbatim}
  148. Will be compiled in the binary. If te \var{BooleanExpression} evaluates to
  149. \var{False}, the RTL will check if the \var{AssertErrorProc} is set. If it
  150. is set, it will be called with as parameters the \var{AssertMessage}
  151. message, the name of the file, the LineNumber and the address. If it is not
  152. set, a runtime error 227 is generated.
  153. The \var{AssertErrorProc} is defined as
  154. \begin{verbatim}
  155. Type
  156. TAssertErrorProc=procedure(const msg,fname:string;lineno,erroraddr:longint);
  157. Var
  158. AssertErrorProc = TAssertErrorProc;
  159. \end{verbatim}
  160. This can be used mainly for debugging purposes. The \file{SYSTEM} unit sets the
  161. \var{AssertErrorProc} to a handler that displays a message on \var{stderr}
  162. and simply exits. The \file{SYSUTILS} unit catches the run-time error 227
  163. and raises an \var{EAssertionFailed} exception.
  164. \subsection{\var{\$DEFINE} : Define a symbol}
  165. The directive
  166. \begin{verbatim}
  167. {$DEFINE name}
  168. \end{verbatim}
  169. defines the symbol \var{name}. This symbol remains defined until the end of
  170. the current module (i.e. unit or program), or until a \var{\$UNDEF name} directive is encountered.
  171. If \var{name} is already defined, this has no effect. \var{Name} is case
  172. insensitive.
  173. The symbols that are defined in a unit, are not saved in the unit file,
  174. so they are also not exported from a unit.
  175. \subsection{\var{\$ELSE} : Switch conditional compilation}
  176. The \var{\{\$ELSE \}} switches between compiling and ignoring the source
  177. text delimited by the preceding \var{\{\$IFxxx\}} and following
  178. \var{\{\$ENDIF\}}. Any text after the \var{ELSE} keyword but before the
  179. brace is ignored:
  180. \begin{verbatim}
  181. {$ELSE some ignored text}
  182. \end{verbatim}
  183. is the same as
  184. \begin{verbatim}
  185. {$ELSE}
  186. \end{verbatim}
  187. This is useful for indication what switch is meant.
  188. \subsection{\var{\$ENDIF} : End conditional compilation}
  189. The \var{\{\$ENDIF\}} directive ends the conditional compilation initiated by the
  190. last \var{\{\$IFxxx\}} directive. Any text after the \var{ENDIF} keyword but
  191. before the closing brace is ignored:
  192. \begin{verbatim}
  193. {$ENDIF some ignored text}
  194. \end{verbatim}
  195. is the same as
  196. \begin{verbatim}
  197. {$ENDIF}
  198. \end{verbatim}
  199. This is useful for indication what switch is meant to be ended.
  200. \subsection{\var{\$ERROR} : Generate error message}
  201. The following code
  202. \begin{verbatim}
  203. {$ERROR This code is erroneous !}
  204. \end{verbatim}
  205. will display an error message when the compiler encounters it,
  206. and increase the error count of the compiler.
  207. The compiler will continue to compile, but no code will be emitted.
  208. \subsection{\var{\$F} : Far or near functions}
  209. This directive is recognized for compatibility with Turbo Pascal. Under the
  210. 32-bit programming model, the concept of near and far calls have no meaning,
  211. hence the directive is ignored. A warning is printed to the screen, telling
  212. you so.
  213. As an example, the following piece of code :
  214. \begin{verbatim}
  215. {$F+}
  216. Procedure TestProc;
  217. begin
  218. Writeln ('Hello From TestProc');
  219. end;
  220. begin
  221. testProc
  222. end.
  223. \end{verbatim}
  224. Generates the following compiler output:
  225. \begin{verbatim}
  226. malpertuus: >pp -vw testf
  227. Compiler: ppc386
  228. Units are searched in: /home/michael;/usr/bin/;/usr/lib/ppc/0.9.1/linuxunits
  229. Target OS: Linux
  230. Compiling testf.pp
  231. testf.pp(1) Warning: illegal compiler switch
  232. 7739 kB free
  233. Calling assembler...
  234. Assembled...
  235. Calling linker...
  236. 12 lines compiled,
  237. 1.00000000000000E+0000
  238. \end{verbatim}
  239. You can see that the verbosity level was set to display warnings.
  240. If you declare a function as \var{Far} (this has the same effect as setting it
  241. between \var{\{\$F+\}...\{\$F-\}} directives), the compiler also generates a
  242. warning :
  243. \begin{verbatim}
  244. testf.pp(3) Warning: FAR ignored
  245. \end{verbatim}
  246. The same story is true for procedures declared as \var{Near}. The warning
  247. displayed in that case is:
  248. \begin{verbatim}
  249. testf.pp(3) Warning: NEAR ignored
  250. \end{verbatim}
  251. \subsection{\var{\$FATAL} : Generate fatal error message}
  252. The following code
  253. \begin{verbatim}
  254. {$FATAL This code is erroneous !}
  255. \end{verbatim}
  256. will display an error message when the compiler encounters it,
  257. and the compiler will immediatly stop the compilation process.
  258. This is mainly useful inc conjunction wih \var{\{\$IFDEF \}} or
  259. \var{\{\$IFOPT \}} statements.
  260. \subsection{\var{\$GOTO} : Support \var{Goto} and \var{Label}}
  261. If \var{\{\$GOTO ON\}} is specified, the compiler will support \var{Goto}
  262. statements and \var{Label} declarations. By default, \var{\$GOTO OFF} is
  263. assumed. This directive corresponds to the \var{-Sg} command-line option.
  264. As an example, the following code can be compiled:
  265. \begin{verbatim}
  266. {$GOTO ON}
  267. label Theend;
  268. begin
  269. If ParamCount=0 then
  270. GoTo TheEnd;
  271. Writeln ('You specified command-line options');
  272. TheEnd:
  273. end.
  274. \end{verbatim}
  275. \begin{remark}
  276. If you compile assembler code not in direct mode (using the intel or
  277. assembler readers) you must declare any labels you use in the assembler
  278. code and use \var{\{\$GOTO ON\}}. If you compile in Direct mode then this is
  279. not necessary.
  280. \end{remark}
  281. \subsection{\var{\$H} or \var{\$LONGSTRINGS} : Use AnsiStrings}
  282. If \var{\{\$LONGSTRINGS ON\}} is specified, the keyword \var{String} (no
  283. length specifier) will be treated as \var{AnsiString}, and the compiler
  284. will treat the corresponding varible as an ansistring, and will
  285. generate corresponding code.
  286. By default, the use of ansistrings is off, corresponding to \var{\{\$H-\}}.
  287. The system unit is compiled without ansistrings, all its functions accept
  288. shortstrng arguments. The same is true for all RTL units, except the
  289. \file{sysutils} unit, which is compiled with ansistrings.
  290. \subsection{\var{\$HINT} : Generate hint message}
  291. If the generation of hints is turned on, through the \var{-vh} command-line
  292. option or the \var{\{\$HINTS ON\}} directive, then
  293. \begin{verbatim}
  294. {$Hint This code should be optimized }
  295. \end{verbatim}
  296. will display a hint message when the compiler encounters it.
  297. By default, no hints are generated.
  298. \subsection{\var{\$HINTS} : Emit hints}
  299. \var{\{\$HINTS ON\}} switches the generation of hints on.
  300. \var{\{\$HINTS OFF\}} switches the generation of hints off.
  301. Contrary to the command-line option \var{-vh} this is a local switch,
  302. this is useful for checking parts of your code.
  303. \subsection{\var{\$IF} : Start conditional compilation}
  304. The directive \var{\{\$IF expr\}} will continue the compilation
  305. if the boolean expression \var{expr} evaluates to \var{true}. If the
  306. compilation evaluates to false, then the source is skipped to the first
  307. \var{\{\$ELSE\}} or \var{\{\$ENDIF\}} directive.
  308. The compiler must be able to evaluate the expression at parse time.
  309. This means that you cannot use variables or constants that are defined in
  310. the source. Macros and symbols may be used, however.
  311. More information on this can be found in the section about
  312. conditionals.
  313. \subsection{\var{\$IFDEF Name} : Start conditional compilation}
  314. If the symbol \var{Name} is not defined then the \var{\{\$IFDEF name\}}
  315. will skip the compilation of the text that follows it to the first
  316. \var{\{\$ELSE\}} or \var{\{\$ENDIF\}} directive.
  317. If \var{Name} is defined, then compilation continues as if the directive
  318. wasn't there.
  319. \subsection{\var{\$IFNDEF} : Start conditional compilation}
  320. If the symbol \var{Name} is defined then the \var{\{\$IFNDEF name\}}
  321. will skip the compilation of the text that follows it to the first
  322. \var{\{\$ELSE\}} or \var{\{\$ENDIF\}} directive.
  323. If it is not defined, then compilation continues as if the directive
  324. wasn't there.
  325. \subsection{\var{\$IFOPT} : Start conditional compilation}
  326. The \var{\{\$IFOPT switch\}} will compile the text that follows it if the
  327. switch \var{switch} is currently in the specified state.
  328. If it isn't in the specified state, then compilation continues after the
  329. corresponding \var{\{\$ELSE\}} or \var{\{\$ENDIF\}} directive.
  330. As an example:
  331. \begin{verbatim}
  332. {$IFOPT M+}
  333. Writeln ('Compiled with type information');
  334. {$ENDIF}
  335. \end{verbatim}
  336. Will compile the writeln statement if generation of type information is on.
  337. \begin{remark}
  338. The \var{\{\$IFOPT\}} directive accepts only short options,
  339. i.e. \var{\{\$IFOPT TYPEINFO\}} will not be accepted.
  340. \subsection{\var{\$INFO} : Generate info message}
  341. \end{remark}
  342. If the generation of info is turned on, through the \var{-vi} command-line
  343. option, then
  344. \begin{verbatim}
  345. {$INFO This was coded on a rainy day by Bugs Bunny }
  346. \end{verbatim}
  347. will display an info message when the compiler encounters it.
  348. This is useful in conjunction with the \var{\{\$IFDEF\}} directive, to show
  349. information about which part of the code is being compiled.
  350. \subsection{\var{\$INLINE} : Allow inline code.}
  351. The \var{\{\$INLINE ON\}} directive tells the compiler that the \var{Inline}
  352. procedure modifier should be allowed. Procedures that are declared inline
  353. are copied to the places where they are called. This has the effect that
  354. there is no actual procedure call, the code of the procedure is just copied
  355. to where the procedure is needed, this results in faster execution speed if
  356. the function or procedure is used a lot.
  357. By default, \var{Inline} procedures are not allowed. You need to specify
  358. this directive if you want to use inlined code. This directive is
  359. equivalent to the command-line switch \var{-Si}.
  360. \begin{remark}
  361. \begin{enumerate}
  362. \item Inline code is NOT exported from a unit. This means that if you call an
  363. inline procedure from another unit, a normal procedure call will be
  364. performed. Only inside units, \var{Inline} procedures are really inline.
  365. \item You cannot make recursive inline functions. i.e. an inline function
  366. that calls itself is not allowed.
  367. \end{enumerate}
  368. \end{remark}
  369. \subsection{\var{\$I} or \var{\$IOCHECKS} : Input/Output checking}
  370. The \var{\{\$I-\}} or \var{\{\$IOCHECKS OFF\}} directive tells the compiler
  371. not to generate input/output checking code in your program. By default, the
  372. compiler generates this code\footnote{This behaviour changed in the 0.99.13
  373. release of the compiler. Earlier versions by default did not generate this
  374. code.}, you must switch it on using the \var{-Ci} command-line switch.
  375. If you compile using the \var{-Ci} compiler switch, the \fpc compiler inserts
  376. input/output checking code after every input/output call in your program.
  377. If an error occurred during input or output, then a run-time error will
  378. be generated. Use this switch if you wish to avoid this behavior.
  379. If you still want to check if something went wrong, you can use the
  380. \var{IOResult} function to see if everything went without problems.
  381. Conversely, \var{\{\$I+\}} will turn error-checking back on, until another
  382. directive is encountered which turns it off again.
  383. The most common use for this switch is to check if the opening of a file
  384. went without problems, as in the following piece of code:
  385. \begin{verbatim}
  386. ...
  387. assign (f,'file.txt');
  388. {$I-}
  389. rewrite (f);
  390. {$I+}
  391. if IOResult<>0 then
  392. begin
  393. Writeln ('Error opening file : "file.txt"');
  394. exit
  395. end;
  396. ...
  397. \end{verbatim}
  398. See the \var{IOResult} function explanantion in the referece manual for a
  399. detailed description of the possible errors that can occur when using
  400. input/output checking.
  401. \subsection{\var{\$I} or \var{\$INCLUDE} : Include file }
  402. The \var{\{\$I filename\}} or \var{\{\$INCLUDE filename\}} directive
  403. tells the compiler to read further statements from the file \var{filename}.
  404. The statements read there will be inserted as if they occurred in the
  405. current file.
  406. The compiler will append the \file{.pp} extension to the file if you don't
  407. specify an extension yourself. Do not put the filename between quotes, as
  408. they will be regarded as part of the file's name.
  409. You can nest included files, but not infinitely deep. The number of files is
  410. restricted to the number of file descriptors available to the \fpc compiler.
  411. Contrary to Turbo Pascal, include files can cross blocks. I.e. you can start
  412. a block in one file (with a \var{Begin} keyword) and end it in another (with
  413. a \var{End} keyword). The smallest entity in an include file must be a token,
  414. i.e. an identifier, keyword or operator.
  415. The compiler will look for the file to include in the following places:
  416. \begin{enumerate}
  417. \item It will look in the path specified in the include file name.
  418. \item It will look in the directory where the current source file is.
  419. \item it will look in all directories specified in the include file search
  420. path.
  421. \end{enumerate}
  422. You can add directories to the include file search path with the \var{-I}
  423. command-line option.
  424. \subsection{\var{\$I} or \var{\$INCLUDE} : Include compiler info}
  425. In this form:
  426. \begin{verbatim}
  427. {$INCLUDE %xxx%}
  428. \end{verbatim}
  429. where \var{xxx} is one of \var{TIME}, \var{DATE}, \var{FPCVERSION} or
  430. \var{FPCTARGET}, will generate a macro with the value of these things.
  431. If \var{xxx} is none of the above, then it is assumed to be the value of
  432. an environment variable. It's value will be fetched, and inserted in the code
  433. as if it were a string.
  434. For example, the following program
  435. \begin{verbatim}
  436. Program InfoDemo;
  437. Const User = {$I %USER%};
  438. begin
  439. Write ('This program was compiled at ',{$I %TIME%});
  440. Writeln (' on ',{$I %DATE%});
  441. Writeln ('By ',User);
  442. Writeln ('Compiler version : ',{$I %FPCVERSION%});
  443. Writeln ('Target CPU : ',{$I %FPCTARGET%});
  444. end.
  445. \end{verbatim}
  446. Creates the following output :
  447. \begin{verbatim}
  448. This program was compiled at 17:40:18 on 1998/09/09
  449. By michael
  450. Compiler version : 0.99.7
  451. Target CPU : i386
  452. \end{verbatim}
  453. % Assembler type
  454. \subsection{\var{\$I386\_XXX} : Specify assembler format}
  455. This switch selects the assembler reader. \var{\{\$I386\_XXX\}}
  456. has the same effect as \var{\{\$ASMMODE XXX\}}, \sees{AsmReader}
  457. This switch is deprecated, the \var{\{\$ASMMODE XXX\}} directive should
  458. be used instead.
  459. \subsection{\var{\$L} or \var{\$LINK} : Link object file}
  460. The \var{\{\$L filename\}} or \var{\{\$LINK filename\}} directive
  461. tells the compiler that the file \file{filename} should be linked to
  462. your program. This cannot be used for libraries, see section
  463. \sees{linklib} for that.
  464. The compiler will look for this file in the following way:
  465. \begin{enumerate}
  466. \item It will look in the path specified in the object file name.
  467. \item It will look in the directory where the current source file is.
  468. \item it will look in all directories specified in the object file search path.
  469. \end{enumerate}
  470. You can add directories to the object file search path with the \var{-Fo}
  471. option.
  472. On \linux systems, the name is case sensitive, and must be typed
  473. exactly as it appears on your system.
  474. \begin{remark} Take care that the object file you're linking is in a
  475. format the linker understands. Which format this is, depends on the platform
  476. you're on. Typing \var{ld} on the command line gives a list of formats
  477. \var{ld} knows about.
  478. \end{remark}
  479. You can pass other files and options to the linker using the \var{-k}
  480. command-line option. You can specify more than one of these options, and
  481. they will be passed to the linker, in the order that you specified them on
  482. the command line, just before the names of the object files that must be
  483. linked.
  484. \subsection{\var{\$LINKLIB} : Link to a library}
  485. \label{se:linklib}
  486. The \var{\{\$LINKLIB name\}} will link to a library \file{name}.
  487. This has the effect of passing \var{-lname} to the linker.
  488. As an example, consider the following unit:
  489. \begin{verbatim}
  490. unit getlen;
  491. interface
  492. {$LINKLIB c}
  493. function strlen (P : pchar) : longint;cdecl;
  494. implementation
  495. function strlen (P : pchar) : longint;cdecl;external;
  496. end.
  497. \end{verbatim}
  498. If one would issue the command
  499. \begin{verbatim}
  500. ppc386 foo.pp
  501. \end{verbatim}
  502. where foo.pp has the above unit in its \var{uses} clause,
  503. then the compiler would link your program to the c library, by passing the
  504. linker the \var{-lc} option.
  505. The same effect could be obtained by removing the linklib directive in the
  506. above unit, and specify \var{-k-lc} on the command-line:
  507. \begin{verbatim}
  508. ppc386 -k-lc foo.pp
  509. \end{verbatim}
  510. \subsection{\var{\$M} or \var{\$TYPEINFO} : Generate type info}
  511. For classes that are compiled in the \var{\{\$M+ \}} or \var{\{\$TYPEINFO ON\}}
  512. state, the compiler will generate Run-Time Type Information (RTTI). All
  513. descendent objects of an object that was compiled in the \var{\{\$M+\}} state
  514. will get RTTI information too, as well as any published classes.
  515. By default, no Run-Time Type Information is generated. The \var{TPersistent}
  516. object that is present in the FCL (Free Component Library) is generated in
  517. the \var{\{\$M+\}} state. The generation of RTTI allows programmers to
  518. stream objects, and to access published properties of objects, without
  519. knowing the actual class of the object.
  520. The run-time type information is accessible through the \var{TypInfo} unit,
  521. which is part of the \fpc Run-Time Library.
  522. \begin{remark}
  523. that the streaming system implemented by \fpc requires that you make
  524. streamable components descendent from \var{TPersistent}.
  525. \end{remark}
  526. \subsection{\var{\$MACRO} : Allow use of macros.}
  527. In the \var{\{\$MACRO ON\}} state, the compiler allows you to use C-style
  528. (although not as elaborate) macros. Macros provide a means for simple text
  529. substitution. More information on using macros can be found in the
  530. \sees{Macros} section. This directive is equivalent to the command-line
  531. switch \var{-Sm}.
  532. By default, macros are not allowed.
  533. \subsection{\var{\$MAXFPUREGISTERS} : Maximum number of FPU registers for variables}
  534. The \var{\{\$MAXFPUREGISTERS XXX\}} directive tells the compiler how much floating point
  535. variables can be kept in the floating point processor registers. This switch is ignored
  536. unless the \var{-Or} (use register variables) optimization is used.
  537. Since version 0.99.14, the \fpc compiler supports floating point register variables;
  538. the content of these variables is not stored on the stack, but is kept in the
  539. floating point processor stack.
  540. This is quite tricky because the Intel FPU stack is limited to 8 entries.
  541. The compiler uses a heuristic algorithm to determine how much variables should be
  542. put onto the stack: in leaf procedures it is limited to 3 and in non leaf
  543. procedures to 1. But in case of a deep call tree or, even worse, a recursive
  544. procedure this can still lead to a FPU stack overflow, so the user can tell
  545. the compiler how much (floating point) variables should be kept in registers.
  546. The directive accepts the following arguments:
  547. \begin{description}
  548. \item [N] where \var{N} is the maximum number of FPU registers to use.
  549. Currently this can be in the range 0 to 7.
  550. \item[Normal] restores the heuristic and standard behavior.
  551. \item[Default] restores the heuristic and standard behaviour.
  552. \end{description}
  553. \begin{remark}
  554. The directive is valid untill the end of the current procedure.
  555. \end{remark}
  556. \subsection{\var{\$MESSAGE} : Generate info message}
  557. If the generation of info is turned on, through the \var{-vi} command-line
  558. option, then
  559. \begin{verbatim}
  560. {$MESSAGE This was coded on a rainy day by Bugs Bunny }
  561. \end{verbatim}
  562. will display an info message when the compiler encounters it. The effect is
  563. the same as the \var{\{\$INFO\}} directive.
  564. \subsection{\var{\$MMX} : Intel MMX support}
  565. As of version 0.9.8, \fpc supports optimization for the \textbf{MMX} Intel
  566. processor (see also \ref{ch:MMXSupport}).
  567. This optimizes certain code parts for the \textbf{MMX} Intel
  568. processor, thus greatly improving speed. The speed is noticed mostly when
  569. moving large amounts of data. Things that change are
  570. \begin{itemize}
  571. \item Data with a size that is a multiple of 8 bytes is moved using the
  572. \var{movq} assembler instruction, which moves 8 bytes at a time
  573. \end{itemize}
  574. \begin{remark} MMX support is NOT emulated on non-MMX systems, i.e. if
  575. the processor doesn't have the MMX extensions, you cannot use the MMX
  576. optimizations.
  577. \end{remark}
  578. When \textbf{MMX} support is on, you aren't allowed to do floating point
  579. arithmetic. You are allowed to move floating point data, but no arithmetic
  580. can be done. If you wish to do floating point math anyway, you must first
  581. switch of \textbf{MMX} support and clear the FPU using the \var{emms}
  582. function of the \file{cpu} unit.
  583. The following example will make this more clear:
  584. \begin{verbatim}
  585. Program MMXDemo;
  586. uses cpu;
  587. var
  588. d1 : double;
  589. a : array[0..10000] of double;
  590. i : longint;
  591. begin
  592. d1:=1.0;
  593. {$mmx+}
  594. { floating point data is used, but we do _no_ arithmetic }
  595. for i:=0 to 10000 do
  596. a[i]:=d2; { this is done with 64 bit moves }
  597. {$mmx-}
  598. emms; { clear fpu }
  599. { now we can do floating point arithmetic }
  600. ....
  601. end.
  602. \end{verbatim}
  603. See, however, the chapter on MMX (\ref{ch:MMXSupport}) for more information
  604. on this topic.
  605. \subsection{\var{\$NOTE} : Generate note message}
  606. If the generation of notes is turned on, through the \var{-vn} command-line
  607. option or the \var{\{\$NOTES ON\}} directive, then
  608. \begin{verbatim}
  609. {$NOTE Ask Santa Claus to look at this code }
  610. \end{verbatim}
  611. will display a note message when the compiler encounters it.
  612. \subsection{\var{\$NOTES} : Emit notes}
  613. \var{\{\$NOTES ON\}} switches the generation of notes on.
  614. \var{\{\$NOTES OFF\}} switches the generation of notes off.
  615. Contrary to the command-line option \var{-vn} this is a local switch,
  616. this is useful for checking parts of your code.
  617. By default, \var{\{\$NOTES \}} is off.
  618. \subsection{\var{\$OUTPUT\_FORMAT} : Specify the output format}
  619. \var{\{\$OUTPUT\_FORMAT format\}} has the same functionality as the \var{-A}
  620. command-line option : It tells the compiler what kind of object file must be
  621. generated. You can specify this switch only {\em before} the \var{Program}
  622. or \var{Unit} clause in your source file. The different kinds of formats are
  623. shown in \seet{Formats}.
  624. The default output format depends on the platform the compiler was compiled
  625. on.
  626. \begin{FPCltable}{ll}{Formats generated by the x86 compiler}{Formats} \hline
  627. Switch value & Generated format \\ \hline
  628. AS & AT\&T assembler file. \\
  629. AS\_AOUT & Go32v1 assembler file.\\
  630. ASW & AT\&T Win32 assembler file. \\
  631. COFF & Go32v2 COFF object file.\\
  632. MASM & Masm assembler file.\\
  633. NASM & Nasm assembler file.\\
  634. NASMCOFF & Nasm assembler file (COFF format).\\
  635. NASMELF & Nasm assembler file (ELF format).\\
  636. PECOFF & PECOFF object file (Win32).\\
  637. TASM & Tasm assembler file.\\
  638. \end{FPCltable}
  639. \subsection{\var{\$P} or \var{\$OPENSTRINGS} : Use open strings}
  640. If this switch is on, all function or procedure parameters of type string
  641. are considered to be open string parameters; this parameter only has effect
  642. for short strings, not for ansistrings.
  643. When using openstrings, the declared type of the string can be different
  644. from the type of string that is actually passed, even for strings that are
  645. passed by reference. The declared size of the string passed can be examined
  646. with the \var{High(P)} call.
  647. Default the use of openstrings is off.
  648. \subsection{\var{\$PACKENUM} : Minimum enumeration type size}
  649. This directive tells the compiler the minimum number of bytes it should
  650. use when storing enumerated types. It is of the following form:
  651. \begin{verbatim}
  652. {$PACKENUM xxx}
  653. {$MINENUMSIZE xxx}
  654. \end{verbatim}
  655. Where the form with \var{\$MINENUMSIZE} is for Delphi compatibility.
  656. \var{xxx} can be one of \var{1,2} or \var{4}, or \var{NORMAL} or
  657. \var{DEFAULT}, corresponding to the default value of 4.
  658. As an alternative form one can use \var{\{\$Z1\}}, \var{\{\$Z2\}}
  659. \var{\{\$Z4\}}. Contrary to Delphi, the default size is 4 bytes
  660. (\var{\{\$Z4\}}).
  661. So the following code
  662. \begin{verbatim}
  663. {$PACKENUM 1}
  664. Type
  665. Days = (monday, tuesday, wednesday, thursday, friday,
  666. saturday, sunday);
  667. \end{verbatim}
  668. will use 1 byte to store a variable of type \var{Days}, whereas it nomally
  669. would use 4 bytes. The above code is equivalent to
  670. \begin{verbatim}
  671. {$Z1}
  672. Type
  673. Days = (monday, tuesday, wednesday, thursday, friday,
  674. saturday, sunday);
  675. \end{verbatim}
  676. \begin{remark}
  677. Sets are always put in 32 bits or 32 bytes, this cannot be changed (yet).
  678. \end{remark}
  679. \subsection{\var{\$PACKRECORDS} : Alignment of record elements}
  680. This directive controls the byte alignment of the elements in a record,
  681. object or class type definition.
  682. It is of the following form:
  683. \begin{verbatim}
  684. {$PACKRECORDS n}
  685. \end{verbatim}
  686. Where \var{n} is one of 1,2,4,16,\var{C}, \var{NORMAL} or \var{DEFAULT}.
  687. This means that the elements of a record that have size greater than \var{n}
  688. will be aligned on \var{n} byte boundaries. Elements with size less than or
  689. equal to \var{n} will be aligned to a natural boundary, i.e. to a power of
  690. two that is equal to or larger than the element's size. The type \var{C}
  691. is used to specify alignment as by the GNU CC compiler. It should be used
  692. only when making import units for C routines.
  693. The default alignment (which can be selected with \var{DEFAULT}) is 2,
  694. contrary to Turbo Pascal, where it is 1.
  695. More information on this and an example program can be found in the reference
  696. guide, in the section about record types.
  697. \begin{remark}
  698. Sets are always put in 32 bit or 32 bytes, this cannot be changed
  699. \end{remark}
  700. \subsection{\var{\$Q} \var{\$OVERFLOWCHECKS}: Overflow checking}
  701. The \var{\{\$Q+\}} or \var{\{\$OVERFLOWCHECKS ON\}} directive turns on
  702. integer overflow checking. This means that the compiler inserts code
  703. to check for overflow when doing computations with integers.
  704. When an overflow occurs, the run-time library will print a message
  705. \var{Overflow at xxx}, and exit the program with exit code 215.
  706. \begin{remark} Overflow checking behaviour is not the same as in
  707. Turbo Pascal since all arithmetic operations are done via 32-bit
  708. values. Furthermore, the \var{Inc()} and \var{Dec} standard system
  709. procedures {\em are} checked for overflow in \fpc, while in Turbo
  710. Pascal they are not.
  711. \end{remark}
  712. Using the \var{\{\$Q-\}} switch switches off the overflow checking code
  713. generation.
  714. The generation of overflow checking code can also be controlled
  715. using the \var{-Co} command line compiler option (see \userref).
  716. \subsection{\var{\$R} or \var{\$RANGECHECKS} : Range checking}
  717. By default, the compiler doesn't generate code to check the ranges of array
  718. indices, enumeration types, subrange types, etc. Specifying the
  719. \var{\{\$R+\}} switch tells the computer to generate code to check these
  720. indices. If, at run-time, an index or enumeration type is specified that is
  721. out of the declared range of the compiler, then a run-time error is
  722. generated, and the program exits with exit code 201. This can happen when
  723. doing a typecast (implicit or explicit) on an enumeration type or subrange
  724. type.
  725. The \var{\{\$RANGECHECKS OFF\}} switch tells the compiler not to generate range checking
  726. code. This may result in faulty program behaviour, but no run-time errors
  727. will be generated.
  728. \begin{remark}
  729. The standard functions \var{val} and \var{Read} will also check ranges
  730. when the call is compiled in \var{\{\$R+\}} mode.
  731. \end{remark}
  732. \subsection{\var{\$SATURATION} : Saturation operations}
  733. This works only on the intel compiler, and MMX support must be on
  734. (\var{\{\$MMX +\}}) for this to have any effect. See the section on
  735. saturation support (\sees{SaturationSupport}) for more information
  736. on the effect of this directive.
  737. \subsection{\var{\$SMARTLINK} : Use smartlinking}
  738. A unit that is compiled in the \var{\{\$SMARTLINK ON\}} state will be
  739. compiled in such a way that it can be used for smartlinking. This means that
  740. the unit is chopped in logical pieces: each procedure is put in it's own
  741. object file, and all object files are put together in a big archive. When
  742. using such a unit, only the pieces of code that you really need or call,
  743. will be linked in your program, thus reducing the size of your executable
  744. substantially.
  745. Beware: using smartlinked units slows down the compilation process, because
  746. a separate object file must be created for each procedure. If you have units
  747. with many functions and procedures, this can be a time consuming process,
  748. even more so if you use an external assembler (the assembler is called to
  749. assemble each procedure or function code block separately).
  750. The smartlinking directive should be specified {\em before} the unit
  751. declaration part:
  752. \begin{verbatim}
  753. {$SMARTLINK ON}
  754. Unit MyUnit;
  755. Interface
  756. ...
  757. \end{verbatim}
  758. This directive is equivalent to the \var{-Cx} command-line switch.
  759. \subsection{\var{\$STATIC} : Allow use of \var{Static} keyword.}
  760. If you specify the \var{\{\$STATIC ON\}} directive, then \var{Static}
  761. methods are allowed for objects. \var{Static} objects methods do not require
  762. a \var{Self} variable. They are equivalent to \var{Class} methods for
  763. classes. By default, \var{Static} methods are not allowed. Class methods
  764. are always allowed.
  765. By default, the address operator returns an untyped pointer.
  766. This directive is equivalent to the \var{-St} command-line option.
  767. \subsection{\var{\$STOP} : Generate fatal error message}
  768. The following code
  769. \begin{verbatim}
  770. {$STOP This code is erroneous !}
  771. \end{verbatim}
  772. will display an error message when the compiler encounters it.
  773. The compiler will immediatly stop the compilation process.
  774. It has the same effect as the \var{\{\$FATAL\}} directive.
  775. \subsection{\var{\$T} or \var{\$TYPEDADDRESS} : Typed address operator (@)}
  776. In the \var{\{\$T+\}} or \var{\{\$TYPEDADDRESS ON\}} state the @ operator,
  777. when applied to a variable, returns a result of type \var{\^{}T}, if the
  778. type of the variable is \var{T}. In the \var{\{\$T-\}} state, the result is
  779. always an untyped pointer, which is assignment compatible with all other
  780. pointer types.
  781. \subsection{\var{\$UNDEF} : Undefine a symbol}
  782. The directive
  783. \begin{verbatim}
  784. {$UNDEF name}
  785. \end{verbatim}
  786. un-defines the symbol \var{name} if it was previously defined.
  787. \var{Name} is case insensitive.
  788. \subsection{\var{\$V} or \var{\$VARSTRINGCHECKS} : Var-string checking}
  789. When in the \var{+} or \var{ON} state, the compiler checks that strings
  790. passed as parameters are of the same, identical, string type as the declared
  791. parameters of the procedure.
  792. \subsection{\var{\$WAIT} : Wait for enter key press}
  793. If the compiler encounters a
  794. \begin{verbatim}
  795. {$WAIT }
  796. \end{verbatim}
  797. directive, it will resume compiling only after the user has pressed the
  798. enter key. If the generation of info messages is turned on, then the compiler
  799. will display the follwing message:
  800. \begin{verbatim}
  801. Press <return> to continue
  802. \end{verbatim}
  803. before waiting for a keypress. Careful ! This may interfere with automatic
  804. compilation processes. It should be used for debugging purposes only.
  805. \subsection{\var{\$WARNING} : Generate warning message}
  806. If the generation of warnings is turned on, through the \var{-vw}
  807. command-line option or the \var{\{\$WARNINGS ON\}} directive, then
  808. \begin{verbatim}
  809. {$WARNING This is dubious code }
  810. \end{verbatim}
  811. will display a warning message when the compiler encounters it.
  812. \subsection{\var{\$WARNINGS} : Emit warnings}
  813. \var{\{\$WARNINGS ON\}} switches the generation of warnings on.
  814. \var{\{\$WARNINGS OFF\}} switches the generation of warnings off.
  815. Contrary to the command-line option \var{-vw} this
  816. is a local switch, this is useful for checking parts of your code.
  817. By default, no warnings are emitted.
  818. \subsection{\var{\$X} or \var{\$EXTENDEDSYNTAX} : Extended syntax}
  819. Extended syntax allows you to drop the result of a function. This means that
  820. you can use a function call as if it were a procedure. Standard this feature
  821. is on. You can switch it off using the \var{\{\$X-\}} or
  822. \var{\{\$EXTENDEDSYNTAX OFF\}}directive.
  823. The following, for instance, will not compile :
  824. \begin{verbatim}
  825. function Func (var Arg : sometype) : longint;
  826. begin
  827. ... { declaration of Func }
  828. end;
  829. ...
  830. {$X-}
  831. Func (A);
  832. \end{verbatim}
  833. The reason this construct is supported is that you may wish to call a
  834. function for certain side-effects it has, but you don't need the function
  835. result. In this case you don't need to assign the function result, saving
  836. you an extra variable.
  837. The command-line compiler switch \var{-Sa1} has the same effect as the
  838. \var{\{\$X+\}} directive.
  839. By default, extended syntax is assumed.
  840. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  841. % Global switches
  842. \section{Global directives}
  843. \label{se:GlobalSwitch}
  844. Global directives affect the whole of the compilation process. That is why
  845. they also have a command-line counterpart. The command-line counterpart is
  846. given for each of the directives.
  847. \subsection{\var{\$APPTYPE} : Specify type of application (Win32 only)}
  848. The \var{\{\$APPTYPE XXX\}} accepts one argument that can have two possible
  849. values : \var{GUI} or \var{CONSOLE}. It is used to tell the windows
  850. Operating system if an application is a console application or a graphical
  851. application. By default, a program compiled by \fpc is a console
  852. application. Running it will display a console window. Specifying the
  853. \var{\{\$APPTYPE GUI\}} directive will mark the application as a graphical
  854. application; no console window will be opened when the application is run.
  855. If run from the command-line, the command prompt will be returned immediatly
  856. after the application was started.
  857. Care should be taken when compiling \var{GUI} applications; the \var{Input}
  858. and \var{Output} files are not available in a GUI application, and
  859. attempting to read from or write to them will result in a run-time error.
  860. It is possible to determine the application type of a windows application
  861. at runtime. The \var{IsConsole} constant, declared in the Win32 system unit
  862. as
  863. \begin{verbatim}
  864. Const
  865. IsConsole : Boolean
  866. \end{verbatim}
  867. contains \var{True} if the application is a console application, \var{False}
  868. if the application is a GUI application.
  869. \subsection{\var{\$D} or \var{\$DEBUGINFO}: Debugging symbols}
  870. When this switch is on (\var{\{\$DEBUGINFO ON\}}),
  871. the compiler inserts GNU debugging information in
  872. the executable. The effect of this switch is the same as the command-line
  873. switch \var{-g}.
  874. By default, insertion of debugging information is off.
  875. \subsection{\var{\$DESCRIPTION}}
  876. This switch is recognised for compatibility only, but is ignored completely
  877. by the compiler. At a later stage, this switch may be activated.
  878. \subsection{\var{\$E} : Emulation of coprocessor}
  879. This directive controls the emulation of the coprocessor. There is no
  880. command-line counterpart for this directive.
  881. \subsubsection{ Intel x86 version }
  882. When this switch is enabled, all floating point instructions
  883. which are not supported by standard coprocessor emulators will give out
  884. a warning.
  885. The compiler itself doesn't do the emulation of the coprocessor.
  886. To use coprocessor emulation under \dos go32v1 there is nothing special
  887. required, as it is handled automatically. (As of version 0.99.10, the
  888. go32v1 platform is no longer be supported)
  889. To use coprocessor emulation under \dos go32v2 you must use the
  890. emu387 unit, which contains correct initialization code for the
  891. emulator.
  892. Under \linux, the kernel takes care of the coprocessor support.
  893. \subsubsection{ Motorola 680x0 version }
  894. When the switch is on, no floating point opcodes are emitted
  895. by the code generator. Instead, internal run-time library routines
  896. are called to do the necessary calculations. In this case all
  897. real types are mapped to the single IEEE floating point type.
  898. \begin{remark} By default, emulation is on. It is possible to
  899. intermix emulation code with real floating point opcodes, as
  900. long as the only type used is single or real.
  901. \end{remark}
  902. \subsection{\var{\$G} : Generate 80286 code}
  903. This option is recognised for Turbo Pascal compatibility, but is ignored,
  904. since the compiler works only on 386 or higher Intel processors.
  905. \subsection{\var{\$INCLUDEPATH} : Specify include path.}
  906. This option serves to specify the include path, where the compiler looks for
  907. include files. \var{\{\$INCLUDEPATH XXX\}} will add \var{XXX} to the include
  908. path. \var{XXX} can contain one or more paths, separated by semi-colons or
  909. colons.
  910. for example
  911. \begin{verbatim}
  912. {$INCLUDEPATH ../inc;../i386}
  913. {$I strings.inc}
  914. \end{verbatim}
  915. Will add the directories \file{../inc} and \file{../i386} to the include
  916. path of the compiler. The compiler will look for the file \file{strings.inc}
  917. in both these directories, and will include the first found file. This directive is
  918. equivalent to the \var{-Fi} command-line switch.
  919. Caution is in order when using this directive: If you distribute files, the
  920. places of the files may not be the same as on your machine; moreover, the
  921. directory structure may be different. In general it would be fair to say
  922. that you should avoid using {\em absolute} paths, instead use {\em relative}
  923. paths, as in the example above. Only use this directive if you are certain
  924. of the places where the files reside. If you are not sure, it is better
  925. practice to use makefiles and makefile variables.
  926. \subsection{\var{\$L} or \var{\$LOCALSYMBOLS}: Local symbol information}
  927. This switch (not to be confused with the \var{\{\$L file\}} file linking
  928. directive) is recognised for Turbo Pascal compatibility, but is ignored.
  929. Generation of symbol information is controlled by the \var{\$D} switch.
  930. \subsection{\var{\$LIBRARYPATH} : Specify library path.}
  931. This option serves to specify the library path, where the linker looks for
  932. static or dynamic libraries. \var{\{\$LIBRARYPATH XXX\}} will add \var{XXX}
  933. to the library path. \var{XXX} can contain one or more paths, separated
  934. by semi-colons or colons.
  935. for example
  936. \begin{verbatim}
  937. {$LIBRARYPATH /usr/X11/lib;/usr/local/lib}
  938. {$LINKLIB X11}
  939. \end{verbatim}
  940. Will add the directories \file{/usr/X11/lib} and \file{/usr/local/lib} to
  941. the linker library path. The linker will look for the library \file{libX11.so}
  942. in both these directories, and use the first found file. This directive is
  943. equivalent to the \var{-Fl} command-line switch.
  944. Caution is in order when using this directive: If you distribute files, the
  945. places of the libraries may not be the same as on your machine; moreover, the
  946. directory structure may be different. In general it would be fair to say
  947. that you should avoid using this directive. If you are not sure, it is better
  948. practice to use makefiles and makefile variables.
  949. \subsection{\var{\$M} or \var{\$MEMORY}: Memory sizes}
  950. This switch can be used to set the heap and stacksize. It's format is as
  951. follows:
  952. \begin{verbatim}
  953. {$M StackSize,HeapSize}
  954. \end{verbatim}
  955. where \var{StackSize} and \var{HeapSize} should be two integer values,
  956. greater than 1024. The first number sets the size of the stack, and the
  957. second the size of the heap. (Stack setting is ignored under \linux).
  958. The two numbers can be set on the command line using the \var{-Ch}
  959. and \var{-Cs} switches.
  960. \subsection{\var{\$MODE} : Set compiler compatibility mode}
  961. The \var{\{\$MODE\}} sets the compatibility mode of the compiler. This
  962. is equivalent to setting one of the command-line options \var{-So},
  963. \var{-Sd}, \var{-Sp} or \var{-S2}. it has the following arguments:
  964. \begin{description}
  965. \item[Default] Default mode. This reverts back to the mode that was set on
  966. the command-line.
  967. \item[Delphi] Delphi compatibility mode. All object-pascal extensions are
  968. enabled. This is the same as the command-line option \var{-Sd}.
  969. \item[TP] Turbo pascal compatibility mode. Object pascal extensions are
  970. disabled, except ansistrings, which remain valid.
  971. This is the same as the command-line option \var{-So}.
  972. \item[FPC] FPC mode. This is the default, if no command-line switch is
  973. supplied.
  974. \item[OBJFPC] Object pascal mode. This is the same as the \var{-S2}
  975. command-line option.
  976. \item[GPC] GNU pascal mode. This is the same as the \var{-Sp} command-line
  977. option.
  978. \end{description}
  979. For an exact description of each of these modes, see appendix \ref{ch:AppD},
  980. on page \pageref{ch:AppD}.
  981. \subsection{\var{\$N} : Numeric processing }
  982. This switch is recognised for Turbo Pascal compatibility, but is otherwise
  983. ignored, since the compiler always uses the coprocessor for floating point
  984. mathematics.
  985. \subsection{\var{\$O} : Overlay code generation }
  986. This switch is recognised for Turbo Pascal compatibility, but is otherwise
  987. ignored.
  988. \subsection{\var{\$OBJECTPATH} : Specify object path.}
  989. This option serves to specify the object path, where the compiler looks for
  990. object files. \var{\{\$OBJECTPATH XXX\}} will add \var{XXX} to the object
  991. path. \var{XXX} can contain one or more paths, separated by semi-colons or
  992. colons.
  993. for example
  994. \begin{verbatim}
  995. {$OBJECTPATH ../inc;../i386}
  996. {$L strings.o}
  997. \end{verbatim}
  998. Will add the directories \file{../inc} and \file{../i386} to the
  999. object path of the compiler. The compiler will look for the file \file{strings.o}
  1000. in both these directories, and will link the first found file in the
  1001. program. This directive is equivalent to the \var{-Fo} command-line switch.
  1002. Caution is in order when using this directive: If you distribute files, the
  1003. places of the files may not be the same as on your machine; moreover, the
  1004. directory structure may be different. In general it would be fair to say
  1005. that you should avoid using {\em absolute} paths, instead use {\em relative}
  1006. paths, as in the example above. Only use this directive if you are certain
  1007. of the places where the files reside. If you are not sure, it is better
  1008. practice to use makefiles and makefile variables.
  1009. \subsection{\var{\$S} : Stack checking}
  1010. The \var{\{\$S+\}} directive tells the compiler to generate stack checking
  1011. code. This generates code to check if a stack overflow occurred, i.e. to see
  1012. whether the stack has grown beyond its maximally allowed size. If the stack
  1013. grows beyond the maximum size, then a run-time error is generated, and the
  1014. program will exit with exit code 202.
  1015. Specifying \var{\{\$S-\}} will turn generation of stack-checking code off.
  1016. The command-line compiler switch \var{-Ct} has the same effect as the
  1017. \var{\{\$S+\}} directive.
  1018. By default, no stack checking is performed.
  1019. \subsection{\var{\$UNITPATH} : Specify unit path.}
  1020. This option serves to specify the unit path, where the compiler looks for
  1021. unit files. \var{\{\$UNITPATH XXX\}} will add \var{XXX} to the unit
  1022. path. \var{XXX} can contain one or more paths, separated by semi-colons or
  1023. colons.
  1024. for example
  1025. \begin{verbatim}
  1026. {$UNITPATH ../units;../i386/units}
  1027. Uses strings;
  1028. \end{verbatim}
  1029. Will add the directories \file{../units} and \file{../i386/units} to the unit
  1030. path of the compiler. The compiler will look for the file \file{strings.ppu}
  1031. in both these directories, and will link the first found file in the
  1032. program. This directive is equivalent to the \var{-Fu} command-line switch.
  1033. Caution is in order when using this directive: If you distribute files, the
  1034. places of the files may not be the same as on your machine; moreover, the
  1035. directory structure may be different. In general it would be fair to say
  1036. that you should avoid using {\em absolute} paths, instead use {\em relative}
  1037. paths, as in the example above. Only use this directive if you are certain
  1038. of the places where the files reside. If you are not sure, it is better
  1039. practice to use makefiles and makefile variables.
  1040. \subsection{\var{\$W} or \var{\$STACKFRAMES} : Generate stackframes}
  1041. The \var{\{\$W\}} switch directove controls the generation of stackframes.
  1042. In the on state (\var{\{\$STACKFRAMES ON\}}), the compiler will generate a
  1043. stackframe for every procedure or function.
  1044. In the off state, the compiler will omit the generation of a stackframe if
  1045. the following conditions are satisfied:
  1046. \begin{itemize}
  1047. \item The procedure has no parameters.
  1048. \item The procedure has no local variables.
  1049. \item If the procedure is not an \var{assembler} procedure, it must not have
  1050. a \var{asm ... end;} block.
  1051. \item it is not a constuctor or desctructor.
  1052. \end{itemize}
  1053. If these conditions are satisfied, the stack frame will be omitted.
  1054. \subsection{\var{\$Y} or \var{\$REFERENCEINFO} : Insert Browser information}
  1055. This switch controls the generation of browser inforation. It is recognized
  1056. for compatibility with Turbo Pascal and Delphi only, as Browser information
  1057. generation is not yet fully supported.
  1058. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1059. % Using conditionals and macros
  1060. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1061. \chapter{Using conditionals, messages and macros}
  1062. \label{ch:CondMessageMacro}
  1063. The \fpc compiler supports conditionals as in normal Turbo Pascal. It does,
  1064. however, more than that. It allows you to make macros which can be used in
  1065. your code, and it allows you to define messages or errors which will be
  1066. displayed when compiling.
  1067. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1068. % Conditionals
  1069. \section{Conditionals}
  1070. \label{se:Conditionals}
  1071. The rules for using conditional symbols are the same as under Turbo Pascal.
  1072. Defining a symbol goes as follows:
  1073. \begin{verbatim}
  1074. {$Define Symbol }
  1075. \end{verbatim}
  1076. From this point on in your code, the compiler knows the symbol \var{Symbol}.
  1077. Symbols are, like the Pascal language, case insensitive.
  1078. You can also define a symbol on the command line. the \var{-dSymbol} option
  1079. defines the symbol \var{Symbol}. You can specify as many symbols on the
  1080. command line as you want.
  1081. Undefining an existing symbol is done in a similar way:
  1082. \begin{verbatim}
  1083. {$Undef Symbol }
  1084. \end{verbatim}
  1085. If the symbol didn't exist yet, this doesn't do anything. If the symbol
  1086. existed previously, the symbol will be erased, and will not be recognized
  1087. any more in the code following the \verb|{$Undef ...}| statement.
  1088. You can also undefine symbols from the command line with the \var{-u}
  1089. command-line switch..
  1090. To compile code conditionally, depending on whether a symbol is defined or
  1091. not, you can enclose the code in a \verb|{$ifdef Symbol}| .. \verb|{$endif}|
  1092. pair. For instance the following code will never be compiled :
  1093. \begin{verbatim}
  1094. {$Undef MySymbol}
  1095. {$ifdef Mysymbol}
  1096. DoSomething;
  1097. ...
  1098. {$endif}
  1099. \end{verbatim}
  1100. Similarly, you can enclose your code in a \verb|{$Ifndef Symbol}| .. \verb|{$endif}|
  1101. pair. Then the code between the pair will only be compiled when the used
  1102. symbol doesn't exist. For example, in the following example, the call to the
  1103. \var{DoSomething} will always be compiled:
  1104. \begin{verbatim}
  1105. {$Undef MySymbol}
  1106. {$ifndef Mysymbol}
  1107. DoSomething;
  1108. ...
  1109. {$endif}
  1110. \end{verbatim}
  1111. You can combine the two alternatives in one structure, namely as follows
  1112. \begin{verbatim}
  1113. {$ifdef Mysymbol}
  1114. DoSomething;
  1115. {$else}
  1116. DoSomethingElse
  1117. {$endif}
  1118. \end{verbatim}
  1119. In this example, if \var{MySymbol} exists, then the call to \var{DoSomething}
  1120. will be compiled. If it doesn't exist, the call to \var{DoSomethingElse} is
  1121. compiled.
  1122. The \fpc compiler defines some symbols before starting to compile your
  1123. program or unit. You can use these symbols to differentiate between
  1124. different versions of the compiler, and between different compilers.
  1125. In \seet{Symbols}, a list of pre-defined symbols is given\footnote{Remark:
  1126. The \var{FPK} symbol is still defined for compatibility with older versions.}. In that table,
  1127. you should change \var{v} with the version number of the compiler
  1128. you're using, \var{r} with the release number and \var{p}
  1129. with the patch-number of the compiler. 'OS' needs to be changed by the type
  1130. of operating system. Currently this can be one of \var{DOS}, \var{GO32V2},
  1131. \var{LINUX}, \var{OS2}, \var{WIN32}, \var{MACOS}, \var{AMIGA} or \var{ATARI}.
  1132. The \var{OS} symbol is undefined if you specify a target that is different from the
  1133. platform you're compiling on.
  1134. The \var{-TSomeOS} option on the command line will define the \var{SomeOS} symbol,
  1135. and will undefine the existing platform symbol\footnote{In versions prior to
  1136. 0.9.4, this didn't happen, thus making Cross-compiling impossible.}.
  1137. \begin{FPCltable}{c}{Symbols defined by the compiler.}{Symbols} \hline
  1138. FPC \\
  1139. VER\var{v} \\
  1140. VER\var{v}\_\var{r} \\
  1141. VER\var{v}\_\var{r}\_\var{p} \\
  1142. OS \\ \hline
  1143. \end{FPCltable}
  1144. As an example : Version 0.9.1 of the compiler, running on a Linux system,
  1145. defines the following symbols before reading the command line arguments:
  1146. \var{FPC}, \var{VER0}, \var{VER0\_9}, \var{VER0\_9\_1} and \var{LINUX}.
  1147. Specifying \var{-TOS2} on the command-line will undefine the \var{LINUX}
  1148. symbol, and will define the \var{OS2} symbol.
  1149. \begin{remark} Symbols, even when they're defined in the interface part of
  1150. a unit, are not available outside that unit.
  1151. \end{remark}
  1152. Except for the Turbo Pascal constructs, from version 0.9.8 and higher,
  1153. the \fpc compiler also supports a stronger conditional compile mechanism:
  1154. The \var{\{\$If \}} construct.
  1155. The prototype of this construct is as follows :
  1156. \begin{verbatim}
  1157. {$If expr}
  1158. CompileTheseLines;
  1159. {$else}
  1160. BetterCompileTheseLines;
  1161. {$endif}
  1162. \end{verbatim}
  1163. In this directive \var{expr} is a Pascal expression which is evaluated using
  1164. strings, unless both parts of a comparision can be evaluated as numbers,
  1165. in which case they are evaluated using numbers\footnote{Otherwise
  1166. \var{\{\$If 8>54\}} would evaluate to \var{True}}.
  1167. If the complete expression evaluates to \var{'0'}, then it is considered
  1168. false and rejected. Otherwise it is considered true and accepted. This may
  1169. have unexpected consequences :
  1170. \begin{verbatim}
  1171. {$If 0}
  1172. \end{verbatim}
  1173. Will evaluate to \var{False} and be rejected, while
  1174. \begin{verbatim}
  1175. {$If 00}
  1176. \end{verbatim}
  1177. Will evaluate to \var{True}.
  1178. You can use any Pascal operator to construct your expression : \var{=, <>,
  1179. >, <, >=, <=, AND, NOT, OR} and you can use round brackets to change the
  1180. precedence of the operators.
  1181. The following example shows you many of the possibilities:
  1182. \begin{verbatim}
  1183. {$ifdef fpc}
  1184. var
  1185. y : longint;
  1186. {$else fpc}
  1187. var
  1188. z : longint;
  1189. {$endif fpc}
  1190. var
  1191. x : longint;
  1192. begin
  1193. {$if (fpc_version=0) and (fpc_release>6) and (fpc_patch>4)}
  1194. {$info At least this is version 0.9.5}
  1195. {$else}
  1196. {$fatal Problem with version check}
  1197. {$endif}
  1198. {$define x:=1234}
  1199. {$if x=1234}
  1200. {$info x=1234}
  1201. {$else}
  1202. {$fatal x should be 1234}
  1203. {$endif}
  1204. {$if 12asdf and 12asdf}
  1205. {$info $if 12asdf and 12asdf is ok}
  1206. {$else}
  1207. {$fatal $if 12asdf and 12asdf rejected}
  1208. {$endif}
  1209. {$if 0 or 1}
  1210. {$info $if 0 or 1 is ok}
  1211. {$else}
  1212. {$fatal $if 0 or 1 rejected}
  1213. {$endif}
  1214. {$if 0}
  1215. {$fatal $if 0 accepted}
  1216. {$else}
  1217. {$info $if 0 is ok}
  1218. {$endif}
  1219. {$if 12=12}
  1220. {$info $if 12=12 is ok}
  1221. {$else}
  1222. {$fatal $if 12=12 rejected}
  1223. {$endif}
  1224. {$if 12<>312}
  1225. {$info $if 12<>312 is ok}
  1226. {$else}
  1227. {$fatal $if 12<>312 rejected}
  1228. {$endif}
  1229. {$if 12<=312}
  1230. {$info $if 12<=312 is ok}
  1231. {$else}
  1232. {$fatal $if 12<=312 rejected}
  1233. {$endif}
  1234. {$if 12<312}
  1235. {$info $if 12<312 is ok}
  1236. {$else}
  1237. {$fatal $if 12<312 rejected}
  1238. {$endif}
  1239. {$if a12=a12}
  1240. {$info $if a12=a12 is ok}
  1241. {$else}
  1242. {$fatal $if a12=a12 rejected}
  1243. {$endif}
  1244. {$if a12<=z312}
  1245. {$info $if a12<=z312 is ok}
  1246. {$else}
  1247. {$fatal $if a12<=z312 rejected}
  1248. {$endif}
  1249. {$if a12<z312}
  1250. {$info $if a12<z312 is ok}
  1251. {$else}
  1252. {$fatal $if a12<z312 rejected}
  1253. {$endif}
  1254. {$if not(0)}
  1255. {$info $if not(0) is OK}
  1256. {$else}
  1257. {$fatal $if not(0) rejected}
  1258. {$endif}
  1259. {$info *************************************************}
  1260. {$info * Now have to follow at least 2 error messages: *}
  1261. {$info *************************************************}
  1262. {$if not(0}
  1263. {$endif}
  1264. {$if not(<}
  1265. {$endif}
  1266. end.
  1267. \end{verbatim}
  1268. As you can see from the example, this construct isn't useful when used
  1269. with normal symbols, only if you use macros, which are explained in
  1270. \sees{Macros}, they can be very useful. When trying this example, you must
  1271. switch on macro support, with the \var{-Sm} command-line switch.
  1272. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1273. % Macros
  1274. \section{Messages}
  1275. \label{se:Messages}
  1276. \fpc lets you define normal, warning and error messages in your code.
  1277. Messages can be used to display useful information, such as copyright
  1278. notices, a list of symbols that your code reacts on etc.
  1279. Warnings can be used if you think some part of your code is still buggy, or
  1280. if you think that a certain combination of symbols isn't useful. In general
  1281. anything which may cause problems when compiling.
  1282. Error messages can be useful if you need a certain symbol to be defined
  1283. to warn that a certain variable isn't defined or so, or when the compiler
  1284. version isn't suitable for your code.
  1285. The compiler treats these messages as if they were generated by the
  1286. compiler. This means that if you haven't turned on warning messages, the
  1287. warning will not be displayed. Errors are always displayed, and the
  1288. compiler stops if 50 errors have occurred. After a fatal error, the compiler
  1289. stops at once.
  1290. For messages, the syntax is as follows :
  1291. \begin{verbatim}
  1292. {$Message Message text }
  1293. \end{verbatim}
  1294. Or
  1295. \begin{verbatim}
  1296. {$Info Message text }
  1297. \end{verbatim}
  1298. For notes:
  1299. \begin{verbatim}
  1300. {$Note Message text }
  1301. \end{verbatim}
  1302. For warnings:
  1303. \begin{verbatim}
  1304. {$Warning Warning Message text }
  1305. \end{verbatim}
  1306. For errors :
  1307. \begin{verbatim}
  1308. {$Error Error Message text }
  1309. \end{verbatim}
  1310. Lastly, for fatal errors :
  1311. \begin{verbatim}
  1312. {$Fatal Error Message text }
  1313. \end{verbatim}
  1314. or
  1315. \begin{verbatim}
  1316. {$Stop Error Message text }
  1317. \end{verbatim}
  1318. The difference between \var{\$Error} and \var{\$FatalError} or \var{\$Stop}
  1319. messages is that when the compiler encounters an error, it still continues
  1320. to compile. With a fatal error, the compiler stops.
  1321. \begin{remark} You cannot use the '\var{\}}' character in your message, since
  1322. this will be treated as the closing brace of the message.
  1323. \end{remark}
  1324. As an example, the following piece of code will generate an error when
  1325. the symbol \var{RequiredVar} isn't defined:
  1326. \begin{verbatim}
  1327. {$ifndef RequiredVar}
  1328. {$Error Requiredvar isn't defined !}
  1329. {$endif}
  1330. \end{verbatim}
  1331. But the compiler will continue to compile. It will not, however, generate a
  1332. unit file or a program (since an error occurred).
  1333. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1334. % Macros
  1335. \section{Macros}
  1336. \label{se:Macros}
  1337. Macros are very much like symbols in their syntax, the difference is that
  1338. macros have a value whereas a symbol simply is defined or is not defined.
  1339. If you want macro support, you need to specify the \var{-Sm} command-line
  1340. switch, otherwise your macro will be regarded as a symbol.
  1341. Defining a macro in your program is done in the same way as defining a symbol;
  1342. in a \var{\{\$define \}} preprocessor statement\footnote{In compiler
  1343. versions older than 0.9.8, the assignment operator for a macros wasn't
  1344. \var{:=}, but \var{=}}:
  1345. \begin{verbatim}
  1346. {$define ident:=expr}
  1347. \end{verbatim}
  1348. If the compiler encounters \var{ident} in the rest of the source file, it
  1349. will be replaced immediately by \var{expr}. This replacement works
  1350. recursive, meaning that when the compiler expanded one of your macros, it
  1351. will look at the resulting expression again to see if another replacement
  1352. can be made. You need to be careful with this, because an infinite loop can
  1353. occur in this manner.
  1354. Here are two examples which illustrate the use of macros:
  1355. \begin{verbatim}
  1356. {$define sum:=a:=a+b;}
  1357. ...
  1358. sum { will be expanded to 'a:=a+b;'
  1359. remark the absence of the semicolon}
  1360. ...
  1361. {$define b:=100}
  1362. sum { Will be expanded recursively to a:=a+100; }
  1363. ...
  1364. \end{verbatim}
  1365. The previous example could go wrong :
  1366. \begin{verbatim}
  1367. {$define sum:=a:=a+b;}
  1368. ...
  1369. sum { will be expanded to 'a:=a+b;'
  1370. remark the absence of the semicolon}
  1371. ...
  1372. {$define b=sum} { DON'T do this !!!}
  1373. sum { Will be infinitely recursively expanded... }
  1374. ...
  1375. \end{verbatim}
  1376. On my system, the last example results in a heap error, causing the compiler
  1377. to exit with a run-time error 203.
  1378. \begin{remark}
  1379. Macros defined in the interface part of a unit are not
  1380. available outside that unit ! They can just be used as a notational
  1381. convenience, or in conditional compiles.
  1382. \end{remark}
  1383. By default, from version 0.9.8 of the compiler on, the compiler predefines three
  1384. macros, containing the version number, the release number and the patch
  1385. number. They are listed in \seet{DefMacros}.
  1386. \begin{FPCltable}{ll}{Predefined macros}{DefMacros} \hline
  1387. Symbol & Contains \\ \hline
  1388. \var{FPC\_VERSION} & The version number of the compiler. \\
  1389. \var{FPC\_RELEASE} & The release number of the compiler. \\
  1390. \var{FPC\_PATCH} & The patch number of the compiler. \\
  1391. \hline
  1392. \end{FPCltable}
  1393. \begin{remark}
  1394. Don't forget that macros support isn't on by default. You
  1395. need to compile with the \var{-Sm} command-line switch.
  1396. \end{remark}
  1397. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1398. % Using assembly language
  1399. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1400. \chapter{Using Assembly language}
  1401. \label{ch:AsmLang}
  1402. \fpc supports inserting of assembler instructions in your code. The
  1403. mechanism for this is the same as under Turbo Pascal. There are, however
  1404. some substantial differences, as will be explained in the following.
  1405. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1406. % Intel syntax
  1407. \section{Intel syntax}
  1408. \label{se:Intel}
  1409. As of version 0.9.7, \fpc supports Intel syntax for the Intel family of Ix86
  1410. processors in it's \var{asm} blocks.
  1411. The Intel syntax in your \var{asm} block is converted to AT\&T syntax by the
  1412. compiler, after which it is inserted in the compiled source.
  1413. The supported assembler constructs are a subset of the normal assembly
  1414. syntax. In what follows we specify what constructs are not supported in
  1415. \fpc, but which exist in Turbo Pascal:
  1416. \begin{itemize}
  1417. \item The \var{TBYTE} qualifier is not supported.
  1418. \item The \var{\&} identifier override is not supported.
  1419. \item The \var{HIGH} operator is not supported.
  1420. \item The \var{LOW} operator is not supported.
  1421. \item The \var{OFFSET} and \var{SEG} operators are not supported.
  1422. use \var{LEA} and the various \var{Lxx} instructions instead.
  1423. \item Expressions with constant strings are not allowed.
  1424. \item Access to record fields via parenthesis is not allowed
  1425. \item Typecasts with normal pascal types are not allowed, only
  1426. recognized assembler typecasts are allowed.\\ Example:
  1427. \begin{verbatim}
  1428. mov al, byte ptr MyWord -- allowed,
  1429. mov al, byte(MyWord) -- allowed,
  1430. mov al, shortint(MyWord) -- not allowed.
  1431. \end{verbatim}
  1432. \item Pascal type typecasts on constants are not allowed. \\
  1433. Example:
  1434. \begin{verbatim}
  1435. const s= 10; const t = 32767;
  1436. \end{verbatim}
  1437. in Turbo Pascal:
  1438. \begin{verbatim}
  1439. mov al, byte(s) -- useless typecast.
  1440. mov al, byte(t) -- syntax error!
  1441. \end{verbatim}
  1442. In this parser, either of those cases will give out a syntax error.
  1443. \item Constant references expressions with constants only are not
  1444. allowed (in all cases they do not work in protected mode,
  1445. under linux i386). \\ Examples:
  1446. \begin{verbatim}
  1447. mov al,byte ptr ['c'] -- not allowed.
  1448. mov al,byte ptr [100h] -- not allowed.
  1449. \end{verbatim}
  1450. (This is due to the limitation of Turbo Assembler).
  1451. \item Brackets within brackets are not allowed
  1452. \item Expressions with segment overrides fully in brackets are
  1453. presently not supported, but they can easily be implemented
  1454. in BuildReference if requested. \\ Example:
  1455. \begin{verbatim}
  1456. mov al,[ds:bx] -- not allowed
  1457. \end{verbatim}
  1458. use instead:
  1459. \begin{verbatim}
  1460. mov al,ds:[bx]
  1461. \end{verbatim}
  1462. \item Possible allowed indexing are as follows:
  1463. \begin{itemize}
  1464. \item \var{Sreg:[REG+REG*SCALING+/-disp]}
  1465. \item \var{SReg:[REG+/-disp]}
  1466. \item \var{SReg:[REG]}
  1467. \item \var{SReg:[REG+REG+/-disp]}
  1468. \item \var{SReg:[REG+REG*SCALING]}
  1469. \end{itemize}
  1470. Where \var{Sreg} is optional and specifies the segment override.
  1471. {\em Notes:}
  1472. \begin{enumerate}
  1473. \item The order of terms is important contrary to Turbo Pascal.
  1474. \item The Scaling value must be a value, and not an identifier
  1475. to a symbol.\\ Examples:
  1476. \begin{verbatim}
  1477. const myscale = 1;
  1478. ...
  1479. mov al,byte ptr [esi+ebx*myscale] -- not allowed.
  1480. \end{verbatim}
  1481. use:
  1482. \begin{verbatim}
  1483. mov al, byte ptr [esi+ebx*1]
  1484. \end{verbatim}
  1485. \end{enumerate}
  1486. \item Possible variable identifier syntax is as follows:
  1487. (Id = Variable or typed constant identifier.)
  1488. \begin{enumerate}
  1489. \item \var{ID}
  1490. \item \var{[ID]}
  1491. \item \var{[ID+expr]}
  1492. \item \var{ID[expr]}
  1493. \end{enumerate}
  1494. Possible fields are as follow:
  1495. \begin{enumerate}
  1496. \item \var{ID.subfield.subfield ...}
  1497. \item \var{[ref].ID.subfield.subfield ...}
  1498. \item \var{[ref].typename.subfield ...}
  1499. \end{enumerate}
  1500. \item Local Labels: Contrary to Turbo Pascal, local labels, must
  1501. at least contain one character after the local symbol indicator.\\
  1502. Example:
  1503. \begin{verbatim}
  1504. @: -- not allowed
  1505. \end{verbatim}
  1506. use instead, for example:
  1507. \begin{verbatim}
  1508. @1: -- allowed
  1509. \end{verbatim}
  1510. \item Contrary to Turbo Pascal local references cannot be used as references,
  1511. only as displacements. \\ example:
  1512. \begin{verbatim}
  1513. lds si,@mylabel -- not allowed
  1514. \end{verbatim}
  1515. \item Contrary to Turbo Pascal, \var{SEGCS}, \var{SEGDS}, \var{SEGES} and
  1516. \var{SEGSS} segment overrides are presently not supported.
  1517. (This is a planned addition though).
  1518. \item Contrary to Turbo Pascal where memory sizes specifiers can
  1519. be practically anywhere, the \fpc Intel inline assembler requires
  1520. memory size specifiers to be outside the brackets. \\
  1521. example:
  1522. \begin{verbatim}
  1523. mov al,[byte ptr myvar] -- not allowed.
  1524. \end{verbatim}
  1525. use:
  1526. \begin{verbatim}
  1527. mov al,byte ptr [myvar] -- allowed.
  1528. \end{verbatim}
  1529. \item Base and Index registers must be 32-bit registers.
  1530. (limitation of the GNU Assembler).
  1531. \item \var{XLAT} is equivalent to \var{XLATB}.
  1532. \item Only Single and Double FPU opcodes are supported.
  1533. \item Floating point opcodes are currently not supported
  1534. (except those which involve only floating point registers).
  1535. \end{itemize}
  1536. The Intel inline assembler supports the following macros :
  1537. \begin{description}
  1538. \item [@Result] represents the function result return value.
  1539. \item [Self] represents the object method pointer in methods.
  1540. \end{description}
  1541. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1542. % AT&T syntax
  1543. \section{AT\&T Syntax}
  1544. \label{se:AttSyntax}
  1545. \fpc uses the \gnu \var{as} assembler to generate its object files for
  1546. the Intel Ix86 processors . Since
  1547. the \gnu assembler uses AT\&T assembly syntax, the code you write should
  1548. use the same syntax. The differences between AT\&T and Intel syntax as used
  1549. in Turbo Pascal are summarized in the following:
  1550. \begin{itemize}
  1551. \item The opcode names include the size of the operand. In general, one can
  1552. say that the AT\&T opcode name is the Intel opcode name, suffixed with a
  1553. '\var{l}', '\var{w}' or '\var{b}' for, respectively, longint (32 bit),
  1554. word (16 bit) and byte (8 bit) memory or register references. As an example,
  1555. the Intel construct \mbox{'\var{mov al bl}} is equivalent to the AT\&T style '\var{movb
  1556. \%bl,\%al}' instruction.
  1557. \item AT\&T immediate operands are designated with '\$', while Intel syntax
  1558. doesn't use a prefix for immediate operands. Thus the Intel construct
  1559. '\var{mov ax, 2}' becomes '\var{movb \$2, \%al}' in AT\&T syntax.
  1560. \item AT\&T register names are preceded by a '\var{\%}' sign.
  1561. They are undelimited in Intel syntax.
  1562. \item AT\&T indicates absolute jump/call operands with '\var{*}', Intel
  1563. syntax doesn't delimit these addresses.
  1564. \item The order of the source and destination operands are switched. AT\&T
  1565. syntax uses '\var{Source, Dest}', while Intel syntax features '\var{Dest,
  1566. Source}'. Thus the Intel construct '\var{add eax, 4}' transforms to
  1567. '\var{addl \$4, \%eax}' in the AT\&T dialect.
  1568. \item Immediate long jumps are prefixed with the '\var{l}' prefix. Thus the
  1569. Intel '\var{call/jmp section:offset'} is transformed to '\var{lcall/ljmp
  1570. \$section,\$offset}'. Similarly the far return is '\var{lret}', instead of the
  1571. Intel '\var{ret far}'.
  1572. \item Memory references are specified differently in AT\&T and Intel
  1573. assembly. The Intel indirect memory reference
  1574. \begin{quote}
  1575. \var{Section:[Base + Index*Scale + Offs]}
  1576. \end{quote}
  1577. is written in AT\&T syntax as :
  1578. \begin{quote}
  1579. \var{Section:Offs(Base,Index,Scale)}
  1580. \end{quote}
  1581. Where \var{Base} and \var{Index} are optional 32-bit base and index
  1582. registers, and \var{Scale} is used to multiply \var{Index}. It can take the
  1583. values 1,2,4 and 8. The \var{Section} is used to specify an optional section
  1584. register for the memory operand.
  1585. \end{itemize}
  1586. More information about the AT\&T syntax can be found in the \var{as} manual,
  1587. although the following differences with normal AT\&T assembly must be taken
  1588. into account :
  1589. \begin{itemize}
  1590. \item Only the following directives are presently supported:
  1591. \begin{description}
  1592. \item[.byte]
  1593. \item[.word]
  1594. \item[.long]
  1595. \item[.ascii]
  1596. \item[.asciz]
  1597. \item[.globl]
  1598. \end{description}
  1599. \item The following directives are recognized but are not
  1600. supported:
  1601. \begin{description}
  1602. \item[.align]
  1603. \item[.lcomm]
  1604. \end{description}
  1605. Eventually they will be supported.
  1606. \item Directives are case sensitive, other identifiers are not case sensitive.
  1607. \item Contrary to GAS local labels/symbols {\em must} start with \var{.L}
  1608. \item The not operator \var{'!'} is not supported.
  1609. \item String expressions in operands are not supported.
  1610. \item CBTW,CWTL,CWTD and CLTD are not supported, use the normal intel
  1611. equivalents instead.
  1612. \item Constant expressions which represent memory references are not
  1613. allowed even though constant immediate value expressions are supported. \\
  1614. examples:
  1615. \begin{verbatim}
  1616. const myid = 10;
  1617. ...
  1618. movl $myid,%eax -- allowed
  1619. movl myid(%esi),%eax -- not allowed.
  1620. \end{verbatim}
  1621. \item When the \var{.globl} directive is found, the symbol following
  1622. it is made public and is immediately emitted.
  1623. Therefore label names with this name will be ignored.
  1624. \item Only Single and Double FPU opcodes are supported.
  1625. \end{itemize}
  1626. The AT\&T inline assembler supports the following macros :
  1627. \begin{description}
  1628. \item [\_\_RESULT] represents the function result return value.
  1629. \item [\_\_SELF] represents the object method pointer in methods.
  1630. \item [\_\_OLDEBP] represents the old base pointer in recusrive routines.
  1631. \end{description}
  1632. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1633. % Calling mechanism
  1634. \section{Calling mechanism}
  1635. \label{se:Calling}
  1636. Procedures and Functions are called with their parameters on the stack.
  1637. Contrary to Turbo Pascal, {\em all} parameters are pushed on the stack, and
  1638. they are pushed {\em right} to {\em left}, instead of left to right for
  1639. Turbo Pascal. This is especially important if you have some assembly
  1640. subroutines in Turbo Pascal which you would like to translate to \fpc.
  1641. Function results are returned in the accumulator, if they fit in the
  1642. register.
  1643. The registers are {\em not} saved when calling a function or procedure. If
  1644. you want to call a procedure or function from assembly language, you must
  1645. save any registers you wish to preserve.
  1646. When you call an object method from assembler, you must load the \var{ESI}
  1647. register with the self pointer of the object or class.
  1648. The first thing a procedure does is saving the base pointer, and setting the
  1649. base pointer equal to the stack pointer. References to the pushed parameters
  1650. and local variables are constructed using the base pointer.
  1651. When the procedure or function exits, it clears the stack.
  1652. When you want your code to be called by a C library or used in a C
  1653. program, you will run into trouble because of this calling mechanism. In C,
  1654. the calling procedure is expected to clear the stack, not the called
  1655. procedure. In other words, the arguments still are on the stack when the
  1656. procedure exits. To avoid this problem, \fpc supports the \var{export}
  1657. modifier. Procedures that are defined using the \var{export} modifier, use a
  1658. C-compatible calling mechanism. This means that they can be called from a
  1659. C program or library, or that you can use them as a callback function.
  1660. This also means that you cannot call this procedure or function from your
  1661. own program, since your program uses the Pascal calling convention.
  1662. However, in the exported function, you can of course call other Pascal
  1663. routines.
  1664. As of version 0.9.8, the \fpc compiler supports also the \var{cdecl} and
  1665. \var{stdcall} modifiers, as found in Delphi. The \var{cdecl} modifier does
  1666. the same as the \var{export} modifier, and \var{stdcall} does nothing, since
  1667. \fpc pushes the paramaters from right to left by default.
  1668. In addition to the Delphi \var{cdecl} construct, \fpc also supports the
  1669. \var{popstack} directive; it is nearly the same a the \var{cdecl} directive,
  1670. only it still mangles the name, i.e. makes it into a name such as the
  1671. compiler uses internally.
  1672. All this is summarized in \seet{Calling}. The first column lists the
  1673. modifier you specify for a procedure declaration. The second one lists the
  1674. order the paramaters are pushed on the stack. The third column specifies who
  1675. is responsible for cleaning the stack: the caller or the called function.
  1676. Finally, the last column specifies if registers are used to pass parameters
  1677. to the function.
  1678. \begin{FPCltable}{llll}{Calling mechanisms in \fpc}{Calling}\hline
  1679. Modifier & Pushing order & Stack cleaned by & Parameters in registers \\
  1680. \hline
  1681. (none) & Right-to-left & Function & No \\
  1682. cdecl & Right-to-left & Caller & No \\
  1683. export & Right-to-left & Caller & No \\
  1684. stdcall & Right-to-left & Function & No \\
  1685. popstack & Right-to-left & Caller & No \\ \hline
  1686. \end{FPCltable}
  1687. More about this can be found in \seec{Linking} on linking.
  1688. \subsection{ Ix86 calling conventions }
  1689. Standard entry code for procedures and functions is as follows on the
  1690. x86 architecture:
  1691. \begin{verbatim}
  1692. pushl %ebp
  1693. movl %esp,%ebp
  1694. \end{verbatim}
  1695. The generated exit sequence for procedure and functions looks as follows:
  1696. \begin{verbatim}
  1697. leave
  1698. ret $xx
  1699. \end{verbatim}
  1700. Where \var{xx} is the total size of the pushed parameters.
  1701. To have more information on function return values take a look at
  1702. \sees{RegConvs}.
  1703. \subsection{ M680x0 calling conventions }
  1704. Standard entry code for procedures and functions is as follows on the
  1705. 680x0 architecture:
  1706. \begin{verbatim}
  1707. move.l a6,-(sp)
  1708. move.l sp,a6
  1709. \end{verbatim}
  1710. The generated exit sequence for procedure and functions looks as follows:
  1711. \begin{verbatim}
  1712. unlk a6
  1713. move.l (sp)+,a0 ; Get return address
  1714. add.l #xx,sp ; Remove allocated stack
  1715. move.l a0,-(sp) ; Put back return address on top of the stack
  1716. \end{verbatim}
  1717. Where \var{xx} is the total size of the pushed parameters.
  1718. To have more information on function return values take a look at
  1719. \sees{RegConvs}.
  1720. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1721. % Telling the compiler what registers have changed
  1722. \section{Signalling changed registers}
  1723. \label{se:RegChanges}
  1724. When the compiler uses variables, it sometimes stores them, or the result of
  1725. some calculations, in the processor registers. If you insert assembler code
  1726. in your program that modifies the processor registers, then this may
  1727. interfere with the compiler's idea about the registers. To avoid this
  1728. problem, \fpc allows you to tell the compiler which registers have changed.
  1729. The compiler will then avoid using these registers. Telling the compiler
  1730. which registers have changed, is done by specifying a set of register names
  1731. behind an assembly block, as follows:
  1732. \begin{verbatim}
  1733. asm
  1734. ...
  1735. end ['R1',...,'Rn'];
  1736. \end{verbatim}
  1737. Here \var{R1} to \var{Rn} are the names of the 32-bit registers you
  1738. modify in your assembly code.
  1739. As an example :
  1740. \begin{verbatim}
  1741. asm
  1742. movl BP,%eax
  1743. movl 4(%eax),%eax
  1744. movl %eax,__RESULT
  1745. end ['EAX'];
  1746. \end{verbatim}
  1747. This example tells the compiler that the \var{EAX} register was modified.
  1748. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1749. % Register conventions
  1750. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1751. \section{Register Conventions}
  1752. \label{se:RegConvs}
  1753. The compiler has different register conventions, depending on the
  1754. target processor used.
  1755. \subsection{ Intel x86 version }
  1756. When optimizations are on, no register can be freely modified, without
  1757. first being saved and then restored. Otherwise, EDI is usually used as
  1758. a scratch register and can be freely used in assembler blocks.
  1759. \subsection{ Motorola 680x0 version }
  1760. Registers which can be freely modified without saving are registers
  1761. D0, D1, D6, A0, A1, and floating point registers FP2 to FP7. All other
  1762. registers are to be considered reserved and should be saved and then
  1763. restored when used in assembler blocks.
  1764. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1765. % Linking issues
  1766. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1767. \chapter{Linking issues}
  1768. \label{ch:Linking}
  1769. When you only use Pascal code, and Pascal units, then you will not see much
  1770. of the part that the linker plays in creating your executable.
  1771. The linker is only called when you compile a program. When compiling units,
  1772. the linker isn't invoked.
  1773. However, there are times that you want to link to C libraries, or to external
  1774. object files that are generated using a C compiler (or even another pascal
  1775. compiler). The \fpc compiler can generate calls to a C function,
  1776. and can generate functions that can be called from C (exported functions).
  1777. More on these calling conventions can be found in \sees{Calling}.
  1778. In general, there are 2 things you must do to use a function that resides in
  1779. an external library or object file:
  1780. \begin{enumerate}
  1781. \item You must make a pascal declaration of the function or procedure you
  1782. want to use.
  1783. \item You must tell the compiler where the function resides, i.e. in what
  1784. object file or what library, so the compiler can link the necessary code in.
  1785. \end{enumerate}
  1786. The same holds for variables. To access a variable that resides in an
  1787. external object file, you must declare it, and tell the compiler where to
  1788. find it.
  1789. The following sections attempt to explain how to do this.
  1790. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1791. % Declaring an external function or procedure
  1792. \section{Using external functions or procedures}
  1793. \label{se:ExternalFunction}
  1794. The first step in using external code blocks is declaring the function you
  1795. want to use. \fpc supports Delphi syntax, i.e. you must use the
  1796. \var{external} directive. The \var{external} directive replaces, in effect,
  1797. the code block of the function.
  1798. The external directive doesn't specify a calling convention; it just tells
  1799. the compiler that the code for a procedure or function resides in an
  1800. external code block.
  1801. There exist four variants of the external directive :
  1802. \begin{enumerate}
  1803. \item A simple external declaration:
  1804. \begin{verbatim}
  1805. Procedure ProcName (Args : TPRocArgs); external;
  1806. \end{verbatim}
  1807. The \var{external} directive tells the compiler that the function resides in
  1808. an external block of code. You can use this together with the \var{\{\$L \}}
  1809. or \var{\{\$LinkLib \}} directives to link to a function or procedure in a
  1810. library or external object file. Object files are looked for in the object
  1811. search path (set by \var{-Fo}) and libraries are searched for in the linker
  1812. path (set by \var{-Fl}).
  1813. \item You can give the \var{external} directive a library name as an
  1814. argument:
  1815. \begin{verbatim}
  1816. Procedure ProcName (Args : TPRocArgs); external 'Name';
  1817. \end{verbatim}
  1818. This tells the compiler that the procedure resides in a library with name
  1819. \var{'Name'}. This method is equivalent to the following:
  1820. \begin{verbatim}
  1821. Procedure ProcName (Args : TPRocArgs);external;
  1822. {$LinkLib 'Name'}
  1823. \end{verbatim}
  1824. \item The \var{external} can also be used with two arguments:
  1825. \begin{verbatim}
  1826. Procedure ProcName (Args : TPRocArgs); external 'Name'
  1827. name 'OtherProcName';
  1828. \end{verbatim}
  1829. This has the same meaning as the previous declaration, only the compiler
  1830. will use the name \var{'OtherProcName'} when linking to the library. This
  1831. can be used to give different names to procedures and functions in an
  1832. external library.
  1833. This method is equivalent to the following code:
  1834. \begin{verbatim}
  1835. Procedure OtherProcName (Args : TProcArgs); external;
  1836. {$LinkLib 'Name'}
  1837. Procedure ProcName (Args : TPRocArgs);
  1838. begin
  1839. OtherProcName (Args);
  1840. end;
  1841. \end{verbatim}
  1842. \item Lastly, onder \windows and \ostwo, there is a fourth possibility
  1843. to specify an external function: In \file{.DLL} files, functions also have
  1844. a unique number (their index). It is possible to refer to these fuctions
  1845. using their index:
  1846. \begin{verbatim}
  1847. Procedure ProcName (Args : TPRocArgs); external 'Name' Index SomeIndex;
  1848. \end{verbatim}
  1849. This tells the compiler that the procedure \var{ProcName} resides in a
  1850. dynamic link library, with index {SomeIndex}.
  1851. \begin{remark}
  1852. Note that this is ONLY available under \windows and \ostwo.
  1853. \end{remark}
  1854. \end{enumerate}
  1855. In earlier versions of the \fpc compiler, the following construct was
  1856. also possible :
  1857. \begin{verbatim}
  1858. Procedure ProcName (Args : TPRocArgs); [ C ];
  1859. \end{verbatim}
  1860. This method is equivalent to the following statement:
  1861. \begin{verbatim}
  1862. Procedure ProcName (Args : TPRocArgs); cdecl; external;
  1863. \end{verbatim}
  1864. However, the \var{[ C ]} directive is no longer supported as of version
  1865. 0.99.5 of \fpc, therefore you should use the \var{external} directive,
  1866. with the \var{cdecl} directive, if needed.
  1867. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1868. % Declaring an external variabl
  1869. \section{Using external variables}
  1870. \label{se:ExternalVars}
  1871. Some libaries or code blocks have variables which they export. You can access
  1872. these variables much in the same way as external functions. To access an
  1873. external variable, you declare it as follows:
  1874. \begin{verbatim}
  1875. Var
  1876. MyVar : MyType; external name 'varname';
  1877. \end{verbatim}
  1878. The effect of this declaration is twofold:
  1879. \begin{enumerate}
  1880. \item No space is allocated for this variable.
  1881. \item The name of the variable used in the assembler code is \var{varname}.
  1882. This is a case sensitive name, so you must be careful.
  1883. \end{enumerate}
  1884. The variable will be
  1885. accessible with it's declared name, i.e. \var{MyVar} in this case.
  1886. A second possibility is the declaration:
  1887. \begin{verbatim}
  1888. Var
  1889. varname : MyType; cvar; external;
  1890. \end{verbatim}
  1891. The effect of this declaration is twofold as in the previous case:
  1892. \begin{enumerate}
  1893. \item The \var{external} modifier ensures that no space is allocated for
  1894. this variable.
  1895. \item The \var{cvar} modifier tells the compiler that the name of the
  1896. variable used in the assembler code is exactly as specified in the
  1897. declaration. This is a case sensitive name, so you must be careful.
  1898. \end{enumerate}
  1899. In this case, you access the variable with it's C name, but case
  1900. insensitive. The first possibility allows you to change the name of the
  1901. external variable for internal use.
  1902. In order to be able to compile such statements, the compiler switch \var{-Sv}
  1903. must be used.
  1904. As an example, let's look at the following C file (in \file{extvar.c}):
  1905. \begin{verbatim}
  1906. /*
  1907. Declare a variable, allocate storage
  1908. */
  1909. int extvar = 12;
  1910. \end{verbatim}
  1911. And the following program (in \file{extdemo.pp}):
  1912. \begin{verbatim}
  1913. Program ExtDemo;
  1914. {$L extvar.o}
  1915. Var { Case sensitive declaration !! }
  1916. extvar : longint; cvar;external;
  1917. I : longint; external name 'extvar';
  1918. begin
  1919. { Extvar can be used case insensitive !! }
  1920. Writeln ('Variable ''extvar'' has value : ',ExtVar);
  1921. Writeln ('Variable ''I'' has value : ',i);
  1922. end.
  1923. \end{verbatim}
  1924. Compiling the C file, and the pascal program:
  1925. \begin{verbatim}
  1926. gcc -c -o extvar.o extvar.c
  1927. ppc386 -Sv extdemo
  1928. \end{verbatim}
  1929. Will produce a program \file{extdemo} which will print
  1930. \begin{verbatim}
  1931. Variable 'extvar' has value : 12
  1932. Variable 'I' has value : 12
  1933. \end{verbatim}
  1934. on your screen.
  1935. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1936. % Linking an object file in your program
  1937. \section{Linking to an object file}
  1938. \label{se:LinkIn}
  1939. Having declared the external function or variable that resides in an object file,
  1940. you can use it as if it was defined in your own program or unit.
  1941. To produce an executable, you must still link the object file in.
  1942. This can be done with the \var{\{\$L file.o\}} directive.
  1943. This will cause the linker to link in the object file \file{file.o}. On
  1944. \linux systems, this filename is case sensitive. Under \dos, case isn't
  1945. important. Note that \var{file.o} must be in the current directory if you
  1946. don't specify a path. The linker will not search for \file{file.o} if it
  1947. isn't found.
  1948. You cannot specify libraries in this way, it is for object files only.
  1949. Here we present an example. Consider that you have some assembly routine that
  1950. calculates the nth Fibonacci number :
  1951. \begin{verbatim}
  1952. .text
  1953. .align 4
  1954. .globl Fibonacci
  1955. .type Fibonacci,@function
  1956. Fibonacci:
  1957. pushl %ebp
  1958. movl %esp,%ebp
  1959. movl 8(%ebp),%edx
  1960. xorl %ecx,%ecx
  1961. xorl %eax,%eax
  1962. movl $1,%ebx
  1963. incl %edx
  1964. loop:
  1965. decl %edx
  1966. je endloop
  1967. movl %ecx,%eax
  1968. addl %ebx,%eax
  1969. movl %ebx,%ecx
  1970. movl %eax,%ebx
  1971. jmp loop
  1972. endloop:
  1973. movl %ebp,%esp
  1974. popl %ebp
  1975. ret
  1976. \end{verbatim}
  1977. Then you can call this function with the following Pascal Program:
  1978. \begin{verbatim}
  1979. Program FibonacciDemo;
  1980. var i : longint;
  1981. Function Fibonacci (L : longint):longint;cdecl;external;
  1982. {$L fib.o}
  1983. begin
  1984. For I:=1 to 40 do
  1985. writeln ('Fib(',i,') : ',Fibonacci (i));
  1986. end.
  1987. \end{verbatim}
  1988. With just two commands, this can be made into a program :
  1989. \begin{verbatim}
  1990. as -o fib.o fib.s
  1991. ppc386 fibo.pp
  1992. \end{verbatim}
  1993. This example supposes that you have your assembler routine in \file{fib.s},
  1994. and your Pascal program in \file{fibo.pp}.
  1995. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1996. % Linking your program to a library
  1997. \section{Linking to a library}
  1998. \label{se:LinkOut}
  1999. To link your program to a library, the procedure depends on how you declared
  2000. the external procedure.
  2001. %If you used thediffers a little from the
  2002. %procedure when you link in an object file. although the declaration step
  2003. %remains the same (see \ref{se:ExternalFunction} on how to do that).
  2004. In case you used the follwing syntax to declare your procedure:
  2005. \begin{verbatim}
  2006. Procedure ProcName (Args : TPRocArgs); external 'Name';
  2007. \end{verbatim}
  2008. You don't need to take additional steps to link your file in, the compiler
  2009. will do all that is needed for you. On \windowsnt it will link to
  2010. \file{Name.dll}, on \linux your program will be linked to library
  2011. \file{libname}, which can be a static or dynamic library.
  2012. In case you used
  2013. \begin{verbatim}
  2014. Procedure ProcName (Args : TPRocArgs); external;
  2015. \end{verbatim}
  2016. You still need to explicity link to the library. This can be done in 2 ways:
  2017. \begin{enumerate}
  2018. \item You can tell the compiler in the source file what library to link to
  2019. using the \var{\{\$LinkLib 'Name'\}} directive:
  2020. \begin{verbatim}
  2021. {$LinkLib 'gpm'}
  2022. \end{verbatim}
  2023. This will link to the \file{gpm} library. On \linux systems, you needn't
  2024. specify the extension or 'lib' prefix of the library. The compiler takes
  2025. care of that. On \dos or \windows systems, you need to specify the full
  2026. name.
  2027. \item You can also tell the compiler on the command-line to link in a
  2028. library: The \var{-k} option can be used for that. For example
  2029. \begin{verbatim}
  2030. ppc386 -k'-lgpm' myprog.pp
  2031. \end{verbatim}
  2032. Is equivalent to the above method, and tells the linker to link to the
  2033. \file{gpm} library.
  2034. \end{enumerate}
  2035. As an example; consider the following program :
  2036. \begin{verbatim}
  2037. program printlength;
  2038. {$linklib c} { Case sensitive }
  2039. { Declaration for the standard C function strlen }
  2040. Function strlen (P : pchar) : longint; cdecl;external;
  2041. begin
  2042. Writeln (strlen('Programming is easy !'));
  2043. end.
  2044. \end{verbatim}
  2045. This program can be compiled with :
  2046. \begin{verbatim}
  2047. ppc386 prlen.pp
  2048. \end{verbatim}
  2049. Supposing, of course, that the program source resides in \file{prlen.pp}.
  2050. To use functions in C that have a variable number of arguments, you must
  2051. compile your unit or program in \var{objfpc} mode or \var{Delphi} mode,
  2052. and use the \var{Array of const} argument, as in the following example:
  2053. \begin{verbatim}
  2054. program testaocc;
  2055. {$mode objfpc}
  2056. Const
  2057. P : Pchar
  2058. = 'example';
  2059. F : Pchar
  2060. = 'This %s uses printf to print numbers (%d) and strings.'#10;
  2061. procedure printf(fm: pchar;args: array of const);cdecl;external 'c';
  2062. begin
  2063. printf(F,[P,123]);
  2064. end.
  2065. \end{verbatim}
  2066. The output of this program looks like this:
  2067. \begin{verbatim}
  2068. This example uses printf to print numbers (123) and strings.
  2069. \end{verbatim}
  2070. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2071. % Making a shared library
  2072. \section{Making libraries}
  2073. \label{se:SharedLib}
  2074. \fpc supports making shared or static libraries in a straightforward and
  2075. easy manner.
  2076. If you want to make libraries for other \fpc programmers, you just need to
  2077. provide a command line switch. If you want C programmers to be able to use
  2078. your code as well, you will need to adapt your code a little. This process
  2079. is described first.
  2080. % Exporting functions.
  2081. \subsection{Exporting functions}
  2082. When exporting functions from a library, there are 2 things you must take in
  2083. account:
  2084. \begin{enumerate}
  2085. \item Calling conventions.
  2086. \item Naming scheme.
  2087. \end{enumerate}
  2088. The calling conventions are controlled by the modifiers \var{cdecl},
  2089. \var{popstack}, \var{pascal}, \var{stdcall}. See \sees{Calling} for more
  2090. information on the different kinds of calling scheme.
  2091. The naming conventions can be controlled by 3 modifiers:
  2092. \begin{description}
  2093. \item [cdecl:\ ] A function that has a \var{cdecl} modifier, will be used
  2094. with C calling conventions, that is, the caller clears the stack. Also
  2095. the mangled name will be the name {\em exactly} as in the declaration.
  2096. \var{cdecl} is part of the function declaration, and hence must be present
  2097. both in the interface and implementation section of a unit.
  2098. \item [export:\ ] A function that has an export modifier, uses also the
  2099. exact declaration name as its mangled name. Under \windowsnt and \ostwo,
  2100. this modifier signals a function that is exported from a DLL.
  2101. The calling conventions used by a \var{export} procedure depend on the OS.
  2102. This keyword can be used only in the implementation section.
  2103. \item [Alias: ] The \var{alias} modifier can be used to give a second
  2104. assembler name to your function. This doesn't modify the calling conventions
  2105. of the function.
  2106. \end{description}
  2107. If you want to make your procedures and functions available to C
  2108. programmers, you can do this very easily. All you need to do is declare the
  2109. functions and procedures that you want to make available as \var{export}, as
  2110. follows:
  2111. \begin{verbatim}
  2112. Procedure ExportedProcedure; export;
  2113. \end{verbatim}
  2114. \begin{remark}
  2115. You can only declare a function as exported in the
  2116. \var{Implementation} section of a unit. This function may {\em not} appear
  2117. in the interface part of a unit. This is logical, since a Pascal routine
  2118. cannot call an exported function, anyway.
  2119. \end{remark}
  2120. However, the generated object file will not contain the name of the function
  2121. as you declared it. The \fpc compiler ''mangles'' the name you give your
  2122. function. It makes the name all-uppercase, and adds the types of all
  2123. parameters to it. There are cases when you want to provide a mangled name
  2124. without changing the calling convention. In such cases, you can use the
  2125. \var{Alias} modifier.
  2126. The \var{Alias} modifier allows you to specify
  2127. another name (a nickname) for your function or procedure.
  2128. The prototype for an aliased function or procedure is as follows :
  2129. \begin{verbatim}
  2130. Procedure AliasedProc; [ Alias : 'AliasName'];
  2131. \end{verbatim}
  2132. The procedure \var{AliasedProc} will also be known as \var{AliasName}. Take
  2133. care, the name you specify is case sensitive (as C is).
  2134. \begin{remark}
  2135. If you use in your unit functions that are in other units, or
  2136. system functions, then the C program will need to link in the object files
  2137. from the units too.
  2138. \end{remark}
  2139. % Exporting variable.
  2140. \subsection{Exporting variables}
  2141. Similarly as when you export functions, you can export variables.
  2142. When exportig variables, one should only consider the names of the
  2143. variables. To declare a variable that should be used by a C program,
  2144. one declares it with the \var{cvar} modifier:
  2145. \begin{verbatim}
  2146. Var MyVar : MyTpe; cvar;
  2147. \end{verbatim}
  2148. This will tell the compiler that the assembler name of the variable (the one
  2149. which is used by C programs) should be exactly as specified in the
  2150. declaration, i.e., case sensitive.
  2151. It is not allowed to declare multiple variables as \var{cvar} in one
  2152. statement, i.e. the following code will produce an error:
  2153. \begin{verbatim}
  2154. var Z1,Z2 : longint;cvar;
  2155. \end{verbatim}
  2156. % Compiling libraries
  2157. \subsection {Compiling libraries}
  2158. Once you have your (adapted) code, with exported and other functions,
  2159. you can compile your unit, and tell the compiler to make it into a library.
  2160. The compiler will simply compile your unit, and perform the necessary steps
  2161. to transform it into a \var{static} or \var{shared} (\var{dynamical}) library.
  2162. You can do this as follows, for a dynamical library:
  2163. \begin{verbatim}
  2164. ppc386 -CD myunit
  2165. \end{verbatim}
  2166. On \linux this will leave you with a file \file{libmyunit.so}. On \windows
  2167. and \ostwo, this will leave you with \file{myunit.dll}.
  2168. If you want a static library, you can do
  2169. \begin{verbatim}
  2170. ppc386 -CS myunit
  2171. \end{verbatim}
  2172. This will leave you with \file{libmyunit.a} and a file \file{myunit.ppu}.
  2173. The \file{myunit.ppu} is the unit file needed by the \fpc compiler.
  2174. The resulting files are then libraries. To make static libraries, you need
  2175. the \file{ranlib} or \var{ar} program on your system. It is standard on any
  2176. \linux system, and is provided with the \file{GCC} compiler under \dos.
  2177. For the dos distribution, a copy of ar is included in the file
  2178. \file{gnuutils.zip}.
  2179. {\em BEWARE:} This command doesn't include anything but the current unit in
  2180. the library. Other units are left out, so if you use code from other units,
  2181. you must deploy them together with your library.
  2182. % Moving units
  2183. \subsection{Moving units into a library}
  2184. You can put multiple units into a library with the \var{ppumove} command, as
  2185. follows:
  2186. \begin{verbatim}
  2187. ppumove -e ppl -o name unit1 unit2 unit3
  2188. \end{verbatim}
  2189. This will move 3 units in 1 library (called \file{libname.so} on linux,
  2190. \file{name.dll} on \windows) and it will create 3 files \file{unit1.ppl},
  2191. \file{unit2.ppl} and \file{unit3.ppl}, which are unit files, but which tell
  2192. the compiler to look in library \var{name} when linking your executable.
  2193. The \var{ppumove} program has options to create statical or dynamical
  2194. libraries. It is provided with the compiler.
  2195. % unit searching
  2196. \subsection{Unit searching strategy}
  2197. When you compile a program or unit, the compiler will by
  2198. default always look for \file{.ppl} files. If it doesn't find one, it will
  2199. look for a \file{.ppu} file.
  2200. To be able to differentiate between units that have been compiled as static
  2201. or dynamic libraries, there are 2 switches:
  2202. \begin{description}
  2203. \item [-XD:\ ] This will define the symbol \var{FPC\_LINK\_DYNAMIC}
  2204. \item [-XS:\ ] This will define the symbol \var{FPC\_LINK\_STATIC}
  2205. \end{description}
  2206. Definition of one symbol will automatically undefine the other.
  2207. These two switches can be used in conjunction with the configuration file
  2208. \file{ppc386.cfg}. The existence of one of these symbols can be used to
  2209. decide which unit search path to set. For example:
  2210. \begin{verbatim}
  2211. # Set unit paths
  2212. #IFDEF FPC_LINK_STATIC
  2213. -Up/usr/lib/fpc/linuxunits/staticunits
  2214. #ENDIF
  2215. #IFDEF FPC_LINK_DYNAMIC
  2216. -Up/usr/lib/fpc/linuxunits/sharedunits
  2217. #ENDIF
  2218. \end{verbatim}
  2219. With such a configuration file, the compiler will look for it's units in
  2220. different directories, depending on whether \var{-XD} or \var{-XS} is used.
  2221. \section{Using smart linking}
  2222. \label{se:SmartLinking}
  2223. You can compile your units using smart linking. When you use smartlinking,
  2224. the compiler creates a series of code blocks that are as small as possible,
  2225. i.e. a code block will contain only the code for one procedure or function.
  2226. When you compile a program that uses a smart-linked unit, the compiler will
  2227. only link in the code that you actually need, and will leave out all other
  2228. code. This will result in a smaller binary, which is loaded in memory
  2229. faster, thus speeding up execution.
  2230. To enable smartlinking, one can give the smartlink option on the command
  2231. line : \var{-Cx}, or one can put the \var{\{\$SMARTLINK ON\}} directive in
  2232. the unit file:
  2233. \begin{verbatim}
  2234. Unit Testunit
  2235. {SMARTLINK ON}
  2236. Interface
  2237. ...
  2238. \end{verbatim}
  2239. Smartlinking will slow down the compilation process, especially for large
  2240. units.
  2241. When a unit \file{foo.pp} is smartlinked, the name of the codefile is
  2242. changed to \file{libfoo.a}.
  2243. Technically speaking, the compiler makes small assembler files for each
  2244. procedure and function in the unit, as well as for all global defined
  2245. variables (whether they're in the interface section or not). It then
  2246. assembles all these small files, and uses \file{ar} to collect the resulting
  2247. object files in one archive.
  2248. Smartlinking and the creation of shared (or dynamic) libraries are mutually
  2249. exclusive, that is, if you turn on smartlinking, then the creation of shared
  2250. libraries is turned of. The creation of static libraries is still possible.
  2251. The reason for this is that it has little sense in making a smarlinked
  2252. dynamical library. The whole shared library is loaded into memory anyway by
  2253. the dynamic linker (or \windowsnt), so there would be no gain in size by
  2254. making it smartlinked.
  2255. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2256. % Objects
  2257. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2258. \chapter{Objects}
  2259. \label{ch:Objects}
  2260. In this short chapter we give some technical things about objects. For
  2261. instructions on how to use and declare objects, see the \refref.
  2262. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2263. % Constructor and Destructor calls.
  2264. \section{Constructor and Destructor calls}
  2265. \label{se:ConsDest}
  2266. When using objects that need virtual methods, the compiler uses two help
  2267. procedures that are in the run-time library. They are called
  2268. \var{Help\_Destructor} and \var{Help\_Constructor}, and they are written in
  2269. assembly language. They are used to allocate the necessary memory if needed,
  2270. and to insert the Virtual Method Table (VMT) pointer in the newly allocated
  2271. object.
  2272. When the compiler encounters a call to an object's constructor,
  2273. it sets up the stack frame for the call, and inserts a call to the
  2274. \var{Help\_Constructor}
  2275. procedure before issuing the call to the real constructor.
  2276. The helper procedure allocates the needed memory (if needed) and inserts the
  2277. VMT pointer in the object. After that, the real constructor is called.
  2278. A call to \var{Help\_Destructor} is inserted in every destructor declaration,
  2279. just before the destructor's exit sequence.
  2280. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2281. % memory storage of Objects
  2282. \section{Memory storage of objects}
  2283. \label{se:ObjMemory}
  2284. Objects are stored in memory just as ordinary records with an extra field :
  2285. a pointer to the Virtual Method Table (VMT). This field is stored first, and
  2286. all fields in the object are stored in the order they are declared.
  2287. This field is initialized by the call to the object's \var{Constructor} method.
  2288. \begin{remark}
  2289. In earlier versions of \fpc, if the object you defined has no virtual methods, then a \var{nil} is stored
  2290. in the VMT pointer. This ensured that the size of objects was equal, whether
  2291. they have virtual methods or not. However, in the \var{0.99} versions of
  2292. free pascal, this was changed for compatibility reasons. If an object
  2293. doesn't have virtual methods, no pointer to a VMT is inserted.
  2294. \end{remark}
  2295. The memory allocated looks as in \seet{ObjMem}.
  2296. \begin{FPCltable}{ll}{Object memory layout}{ObjMem} \hline
  2297. Offset & What \\ \hline
  2298. +0 & Pointer to VMT. \\
  2299. +4 & Data. All fields in the order the've been declared. \\
  2300. ... & \\
  2301. \hline
  2302. \end{FPCltable}
  2303. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2304. % The virtual method table.
  2305. \section{The Virtual Method Table}
  2306. \label{se:VMT}
  2307. The Virtual Method Table (VMT) for each object type consists of 2 check
  2308. fields (containing the size of the data), a pointer to the object's ancestor's
  2309. VMT (\var{Nil} if there is no ancestor), and then the pointers to all virtual
  2310. methods. The VMT layout is illustrated in \seet{VMTMem}.
  2311. The VMT is constructed by the compiler. Every instance of an object receives
  2312. a pointer to its VMT.
  2313. \begin{FPCltable}{ll}{Virtual Method Table memory layout}{VMTMem} \hline
  2314. Offset & What \\ \hline
  2315. +0 & Size of object type data \\
  2316. +4 & Minus the size of object type data. Enables determining of valid VMT
  2317. pointers. \\
  2318. +8 & Pointer to ancestor VMT, \var{Nil} if no ancestor available.\\
  2319. +12 & Pointers to the virtual methods. \\
  2320. ... & \\
  2321. \hline
  2322. \end{FPCltable}
  2323. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2324. % Generated code
  2325. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2326. \chapter{Generated code}
  2327. \label{ch:GenCode}
  2328. The \fpc compiler relies on the assembler to make object files. It generates
  2329. just the assembly language file. In the following two sections, we discuss
  2330. what is generated when you compile a unit or a program.
  2331. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2332. % Units
  2333. \section{Units}
  2334. \label{se:Units}
  2335. When you compile a unit, the \fpc compiler generates 2 files :
  2336. \begin{enumerate}
  2337. \item A unit description file (with extension \file{.ppu}, or \file{.ppw on
  2338. \windowsnt}).
  2339. \item An assembly language file (with extension \file{.s}).
  2340. \end{enumerate}
  2341. The assembly language file contains the actual source code for the
  2342. statements in your unit, and the necessary memory allocations for any
  2343. variables you use in your unit. This file is converted by the assembler to
  2344. an object file (with extension \file{.o}) which can then be linked to other
  2345. units and your program, to form an executable.
  2346. By default (compiler version 0.9.4 and up), the assembly file is removed
  2347. after it has been compiled. Only in the case of the \var{-s} command-line
  2348. option, the assembly file must be left on disk, so the assembler can be
  2349. called later. You can disable the erasing of the assembler file with the
  2350. \var{-a} switch.
  2351. The unit file contains all the information the compiler needs to use the
  2352. unit:
  2353. \begin{enumerate}
  2354. \item Other used units, both in interface and implementation.
  2355. \item Types and variables from the interface section of the unit.
  2356. \item Function declarations from the interface section of the unit.
  2357. \item Some debugging information, when compiled with debugging.
  2358. \item A date and time stamp.
  2359. \end{enumerate}
  2360. Macros, symbols and compiler directives are {\em not} saved to the unit
  2361. description file. Aliases for functions are also not written to this file,
  2362. which is logical, since they cannot appear in the interface section of a
  2363. unit.
  2364. The detailed contents and structure of this file are described in the first
  2365. appendix. You can examine a unit description file using the \file{ppudump}
  2366. program, which shows the contents of the file.
  2367. If you want to distribute a unit without source code, you must provide both
  2368. the unit description file and the object file.
  2369. You can also provide a C header file to go with the object file. In that
  2370. case, your unit can be used by someone who wishes to write his programs in
  2371. C. However, you must make this header file yourself since the \fpc compiler
  2372. doesn't make one for you.
  2373. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2374. % Programs
  2375. \section{Programs}
  2376. \label{se:Programs}
  2377. When you compile a program, the compiler produces again 2 files :
  2378. \begin{enumerate}
  2379. \item An assembly language file containing the statements of your program,
  2380. and memory allocations for all used variables.
  2381. \item A linker response file. This file contains a list of object files the
  2382. linker must link together.
  2383. \end{enumerate}
  2384. The link response file is, by default, removed from the disk. Only when you
  2385. specify the \var{-s} command-line option or when linking fails, then the file
  2386. is left on the disk. It is named \file{link.res}.
  2387. The assembly language file is converted to an object file by the assembler,
  2388. and then linked together with the rest of the units and a program header, to
  2389. form your final program.
  2390. The program header file is a small assembly program which provides the entry
  2391. point for the program. This is where the execution of your program starts,
  2392. so it depends on the operating system, because operating systems pass
  2393. parameters to executables in wildly different ways.
  2394. It's name is \file{prt0.o}, and the
  2395. source file resides in \file{prt0.s} or some variant of this name. It
  2396. usually resided where the system unit source for your system resides.
  2397. It's main function is to save the environment and command-line arguments and
  2398. set up the stack. Then it calls the main program.
  2399. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2400. % MMX Support
  2401. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2402. \chapter{Intel MMX support}
  2403. \label{ch:MMXSupport}
  2404. \section{What is it about ?}
  2405. \label{se:WhatisMMXabout}
  2406. \fpc supports the new MMX (Multi-Media extensions)
  2407. instructions of Intel processors. The idea of MMX is to
  2408. process multiple data with one instruction, for example the processor
  2409. can add simultaneously 4 words. To implement this efficiently, the
  2410. Pascal language needs to be extended. So Free Pascal allows
  2411. to add for example two \var{array[0..3] of word},
  2412. if MMX support is switched on. The operation is done
  2413. by the \var{MMX} unit and allows people without assembler knowledge to take
  2414. advantage of the MMX extensions.
  2415. Here is an example:
  2416. \begin{verbatim}
  2417. uses
  2418. MMX; { include some predefined data types }
  2419. const
  2420. { tmmxword = array[0..3] of word;, declared by unit MMX }
  2421. w1 : tmmxword = (111,123,432,4356);
  2422. w2 : tmmxword = (4213,63456,756,4);
  2423. var
  2424. w3 : tmmxword;
  2425. l : longint;
  2426. begin
  2427. if is_mmx_cpu then { is_mmx_cpu is exported from unit mmx }
  2428. begin
  2429. {$mmx+} { turn mmx on }
  2430. w3:=w1+w2;
  2431. {$mmx-}
  2432. end
  2433. else
  2434. begin
  2435. for i:=0 to 3 do
  2436. w3[i]:=w1[i]+w2[i];
  2437. end;
  2438. end.
  2439. \end{verbatim}
  2440. \section{Saturation support}
  2441. \label{se:SaturationSupport}
  2442. One important point of MMX is the support of saturated operations.
  2443. If a operation would cause an overflow, the value stays at the
  2444. highest or lowest possible value for the data type:
  2445. If you use byte values you get normally 250+12=6. This is very
  2446. annoying when doing color manipulations or changing audio samples,
  2447. when you have to do a word add and check if the value is greater than
  2448. 255. The solution is saturation: 250+12 gives 255.
  2449. Saturated operations are supported by the \var{MMX} unit. If you
  2450. want to use them, you have simple turn the switch saturation on:
  2451. \var{\$saturation+}
  2452. Here is an example:
  2453. \begin{verbatim}
  2454. Program SaturationDemo;
  2455. {
  2456. example for saturation, scales data (for example audio)
  2457. with 1.5 with rounding to negative infinity
  2458. }
  2459. var
  2460. audio1 : tmmxword;
  2461. const
  2462. helpdata1 : tmmxword = ($c000,$c000,$c000,$c000);
  2463. helpdata2 : tmmxword = ($8000,$8000,$8000,$8000);
  2464. begin
  2465. { audio1 contains four 16 bit audio samples }
  2466. {$mmx+}
  2467. { convert it to $8000 is defined as zero, multiply data with 0.75 }
  2468. audio1:=tmmxfixed16(audio1+helpdata2)*tmmxfixed(helpdata1);
  2469. {$saturation+}
  2470. { avoid overflows (all values>$7fff becomes $ffff) }
  2471. audio1:=(audio1+helpdata2)-helpdata2;
  2472. {$saturation-}
  2473. { now mupltily with 2 and change to integer }
  2474. audio1:=(audio1 shl 1)-helpdata2;
  2475. {$mmx-}
  2476. end.
  2477. \end{verbatim}
  2478. \section{Restrictions of MMX support}
  2479. \label{se:MMXrestrictions}
  2480. In the beginning of 1997 the MMX instructions were introduced in the
  2481. Pentium processors, so multitasking systems wouldn't save the
  2482. newly introduced MMX registers. To work around that problem, Intel
  2483. mapped the MMX registers to the FPU register.
  2484. The consequence is that
  2485. you can't mix MMX and floating point operations. After using
  2486. MMX operations and before using floating point operations, you
  2487. have to call the routine \var{EMMS} of the \var{MMX} unit.
  2488. This routine restores the FPU registers.
  2489. {\em Careful:} The compiler doesn't warn if you mix floating point and
  2490. MMX operations, so be careful.
  2491. The MMX instructions are optimized for multi media (what else?).
  2492. So it isn't possible to perform each operation, some opertions
  2493. give a type mismatch, see section \ref {se:SupportedMMX} for the supported
  2494. MMX operations
  2495. An important restriction is that MMX operations aren't range or overflow
  2496. checked, even when you turn range and overflow checking on. This is due to
  2497. the nature of MMX operations.
  2498. The \var{MMX} unit must always be used when doing MMX operations
  2499. because the exit code of this unit clears the MMX unit. If it wouldn't do
  2500. that, other program will crash. A consequence of this is that you can't use
  2501. MMX operations in the exit code of your units or programs, since they would
  2502. interfere with the exit code of the \var{MMX} unit. The compiler can't
  2503. check this, so you are responsible for this !
  2504. \section{Supported MMX operations}
  2505. \label{se:SupportedMMX}
  2506. {\em Still to be written...}
  2507. \section{Optimizing MMX support}
  2508. \label{se:OptimizingMMX}
  2509. Here are some helpful hints to get optimal performance:
  2510. \begin{itemize}
  2511. \item The \var{EMMS} call takes a lot of time, so try to seperate floating
  2512. point and MMX operations.
  2513. \item Use MMX only in low level routines because the compiler
  2514. saves all used MMX registers when calling a subroutine.
  2515. \item The NOT-operator isn't supported natively by MMX, so the
  2516. compiler has to generate a workaround and this operation
  2517. is inefficient.
  2518. \item Simple assignements of floating point numbers don't access
  2519. floating point registers, so you need no call to the \var{EMMS}
  2520. procedure. Only when doing arithmetic, you need to call the \var{EMMS}
  2521. procedure.
  2522. \end{itemize}
  2523. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2524. % Memory issues
  2525. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2526. \chapter{Memory issues}
  2527. \label{ch:Memory}
  2528. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2529. % The 32-bit model
  2530. \section{The 32-bit model.}
  2531. \label{se:ThirtytwoBit}
  2532. The \fpc compiler issues 32-bit code. This has several consequences:
  2533. \begin{itemize}
  2534. \item You need a 386 processor to run the generated code. The
  2535. compiler functions on a 286 when you compile it using Turbo Pascal,
  2536. but the generated programs cannot be assembled or executed.
  2537. \item You don't need to bother with segment selectors. Memory can be
  2538. addressed using a single 32-bit pointer.
  2539. The amount of memory is limited only by the available amount of (virtual)
  2540. memory on your machine.
  2541. \item The structures you define are unlimited in size. Arrays can be as long
  2542. as you want. You can request memory blocks from any size.
  2543. \end{itemize}
  2544. The fact that 32-bit code is used, means that some of the older Turbo Pascal
  2545. constructs and functions are obsolete. The following is a list of functions
  2546. which shouldn't be used anymore:
  2547. \begin{description}
  2548. \item [Seg()] : Returned the segment of a memory address. Since segments have
  2549. no more meaning, zero is returned in the \fpc run-time library implementation of
  2550. \var{Seg}.
  2551. \item [Ofs()] : Returned the offset of a memory address. Since segments have
  2552. no more meaning, the complete address is returned in the \fpc implementation
  2553. of this function. This has as a consequence that the return type is
  2554. \var{Longint} instead of \var{Word}.
  2555. \item [Cseg(), Dseg()] : Returned, respectively, the code and data segments
  2556. of your program. This returns zero in the \fpc implementation of the
  2557. system unit, since both code and data are in the same memory space.
  2558. \item [Ptr:] Accepted a segment and offset from an address, and would return
  2559. a pointer to this address. This has been changed in the run-time library, it
  2560. now simply returns the offset.
  2561. \item [memw and mem] These arrays gave access to the \dos memory. \fpc
  2562. supports them on the go32v2 platform, they are mapped into \dos memory
  2563. space. You need the \var{GO32} unit for this. On other platforms, they are
  2564. {\em not} supported
  2565. \end{description}
  2566. You shouldn't use these functions, since they are very non-portable, they're
  2567. specific to \dos and the ix86 processor. The \fpc compiler is designed to be
  2568. portable to other platforms, so you should keep your code as portable as
  2569. possible, and not system specific. That is, unless you're writing some driver
  2570. units, of course.
  2571. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2572. % The stack
  2573. \section{The stack}
  2574. \label{se:Stack}
  2575. The stack is used to pass parameters to procedures or functions,
  2576. to store local variables, and, in some cases, to return function
  2577. results.
  2578. When a function or procedure is called, then the following is done by the
  2579. compiler :
  2580. \begin{enumerate}
  2581. \item If there are any parameters to be passed to the procedure, they are
  2582. pushed from right to left on the stack.
  2583. \item If a function is called that returns a variable of type \var{String},
  2584. \var{Set}, \var{Record}, \var{Object} or \var{Array}, then an address to
  2585. store the function result in, is pushed on the stack.
  2586. \item If the called procedure or function is an object method, then the
  2587. pointer to \var{self} is pushed on the stack.
  2588. \item If the procedure or function is nested in another function or
  2589. procedure, then the frame pointer of the parent procedure is pushed on the
  2590. stack.
  2591. \item The return address is pushed on the stack (This is done automatically
  2592. by the instruction which calls the subroutine).
  2593. \end{enumerate}
  2594. The resulting stack frame upon entering looks as in \seet{StackFrame}.
  2595. \begin{FPCltable}{llc}{Stack frame when calling a procedure}{StackFrame}
  2596. \hline
  2597. Offset & What is stored & Optional ? \\ \hline
  2598. +x & parameters & Yes \\
  2599. +12 & function result & Yes \\
  2600. +8 & self & Yes \\
  2601. +4 & Return address & No\\
  2602. +0 & Frame pointer of parent procedure & Yes \\ \hline
  2603. \end{FPCltable}
  2604. \subsection{ Intel x86 version }
  2605. The stack is cleared with the \var{ret} I386 instruction, meaning that the
  2606. size of all pushed parameters is limited to 64K.
  2607. \subsubsection{ DOS }
  2608. Under the DOS targets, the default stack is set to 256Kb. This value
  2609. cannot be modified for the GO32V1 target. But this can be modified
  2610. with the GO32V2 target using a special DJGPP utility \var{stubedit}.
  2611. It is to note that the stack size may be changed with some compiler
  2612. switches, this stack size, if \emph{greater} then the default stack
  2613. size will be used instead, otherwise the default stack size is used.
  2614. \subsubsection{ Linux }
  2615. Under \linux, stack size is only limited by the available memory of
  2616. the system.
  2617. \subsubsection{ Windows }
  2618. Under \windows, stack size is only limited by the available memory of
  2619. the system.
  2620. \subsubsection{ OS/2 }
  2621. Under \ostwo, stack size is determined by one of the runtime
  2622. environment variables set for EMX. Therefore, the stack size
  2623. is user defined.
  2624. \subsection{ Motorola 680x0 version }
  2625. All depending on the processor target, the stack can be cleared in two
  2626. manners, if the target processor is a MC68020 or higher, the stack will
  2627. be cleared with a simple \var{rtd} instruction, meaning that the size
  2628. of all pushed parameters is limited to 32K.
  2629. Otherwise on MC68000/68010 processors, the stack clearing mechanism
  2630. is sligthly more complicated, the exit code will look like this:
  2631. \begin{verbatim}
  2632. {
  2633. move.l (sp)+,a0
  2634. add.l paramsize,a0
  2635. move.l a0,-(sp)
  2636. rts
  2637. }
  2638. \end{verbatim}
  2639. \subsubsection{ Amiga }
  2640. Under AmigaOS, stack size is determined by the user, which sets this
  2641. value using the stack program. Typical sizes range from 4K to 40K.
  2642. \subsubsection{ Atari }
  2643. Under Atari TOS, stack size is currently limited to 8K, and it cannot
  2644. be modified. This may change in a future release of the compiler.
  2645. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2646. % The heap
  2647. \section{The heap}
  2648. \label{se:Heap}
  2649. The heap is used to store all dynamic variables, and to store class
  2650. instances. The interface to the heap is the same as in Turbo Pascal,
  2651. although the effects are maybe not the same. On top of that, the \fpc
  2652. run-time library has some extra possibilities, not available in Turbo
  2653. Pascal. These extra possibilities are explained in the next subsections.
  2654. % The heap grows
  2655. \subsection{The heap grows}
  2656. \fpc supports the \var{HeapError} procedural variable. If this variable is
  2657. non-nil, then it is called in case you try to allocate memory, and the heap
  2658. is full. By default, \var{HeapError} points to the \var{GrowHeap} function,
  2659. which tries to increase the heap.
  2660. The growheap function issues a system call to try to increase the size of the
  2661. memory available to your program. It first tries to increase memory in a 1 Mb.
  2662. chunk. If this fails, it tries to increase the heap by the amount you
  2663. requested from the heap.
  2664. If the call to \var{GrowHeap} has failed, then a run-time error is generated,
  2665. or nil is returned, depending on the \var{GrowHeap} result.
  2666. If the call to \var{GrowHeap} was successful, then the needed memory will be
  2667. allocated.
  2668. % Using Blocks
  2669. \subsection{Using Blocks}
  2670. If you need to allocate a lot of small blocks for a small period, then you
  2671. may want to recompile the run-time library with the \var{USEBLOCKS} symbol
  2672. defined. If it is recompiled, then the heap management is done in a
  2673. different way.
  2674. The run-time library keeps a linked list of allocated blocks with size
  2675. up to 256 bytes\footnote{The size can be set using the \var{max\_size}
  2676. constant in the \file{heap.inc} source file.}. By default, it keeps 32 of
  2677. these lists\footnote{The actual size is \var{max\_size div 8}.}.
  2678. When a piece of memory in a block is deallocated, the heap manager doesn't
  2679. really deallocate the occupied memory. The block is simply put in the linked
  2680. list corresponding to its size.
  2681. When you then again request a block of memory, the manager checks in the
  2682. list if there is a non-allocated block which fits the size you need (rounded
  2683. to 8 bytes). If so, the block is used to allocate the memory you requested.
  2684. This method of allocating works faster if the heap is very fragmented, and
  2685. you allocate a lot of small memory chunks.
  2686. Since it is invisible to the program, this provides an easy way of improving
  2687. the performance of the heap manager.
  2688. % The splitheap
  2689. \subsection{Using the split heap}
  2690. \begin{remark}
  2691. The split heap is still somewhat buggy. Use at your own risk for the moment.
  2692. \end{remark}
  2693. The split heap can be used to quickly release a lot of blocks you allocated
  2694. previously.
  2695. Suppose that in a part of your program, you allocate a lot of memory chunks
  2696. on the heap. Suppose that you know that you'll release all this memory when
  2697. this particular part of your program is finished.
  2698. In Turbo Pascal, you could foresee this, and mark the position of the heap
  2699. (using the \var{Mark} function) when entering this particular part of your
  2700. program, and release the occupied memory in one call with the \var{Release}
  2701. call.
  2702. For most purposes, this works very good. But sometimes, you may need to
  2703. allocate something on the heap that you {\em don't} want deallocated when you
  2704. release the allocated memory. That is where the split heap comes in.
  2705. When you split the heap, the heap manager keeps 2 heaps: the base heap (the
  2706. normal heap), and the temporary heap. After the call to split the heap,
  2707. memory is allocated from the temporary heap. When you're finished using all
  2708. this memory, you unsplit the heap. This clears all the memory on the split
  2709. heap with one call. After that, memory will be allocated from the base heap
  2710. again.
  2711. So far, nothing special, nothing that can't be done with calls to \var{mark}
  2712. and \var{release}. Suppose now that you have split the heap, and that you've
  2713. come to a point where you need to allocate memory that is to stay allocated
  2714. after you unsplit the heap again. At this point, mark and release are of no
  2715. use. But when using the split heap, you can tell the heap manager to
  2716. --temporarily-- use the base heap again to allocate memory.
  2717. When you've allocated the needed memory, you can tell the heap manager that
  2718. it should start using the temporary heap again.
  2719. When you're finished using the temporary heap, you release it, and the
  2720. memory you allocated on the base heap will still be allocated.
  2721. To use the split-heap, you must recompile the run-time library with the \var{TempHeap}
  2722. symbol defined.
  2723. This means that the following functions are available :
  2724. \begin{verbatim}
  2725. procedure Split_Heap;
  2726. procedure Switch_To_Base_Heap;
  2727. procedure Switch_To_Temp_Heap;
  2728. procedure Switch_Heap;
  2729. procedure ReleaseTempHeap;
  2730. procedure GetTempMem(var p : pointer;size : longint);
  2731. \end{verbatim}
  2732. \var{Split\_Heap} is used to split the heap. It cannot be called two times
  2733. in a row, without a call to \var{releasetempheap}. \var{Releasetempheap}
  2734. completely releases the memory used by the temporary heap.
  2735. Switching temporarily back to the base heap can be done using the
  2736. \var{Switch\_To\_Base\_Heap} call, and returning to the temporary heap is done
  2737. using the \var{Switch\_To\_Temp\_Heap} call. Switching from one to the other
  2738. without knowing on which one your are right now, can be done using the
  2739. \var{Switch\_Heap} call, which will split the heap first if needed.
  2740. A call to \var{GetTempMem} will allocate a memory block on the temporary
  2741. heap, whatever the current heap is. The current heap after this call will be
  2742. the temporary heap.
  2743. Typically, what will appear in your code is the following sequence :
  2744. \begin{verbatim}
  2745. Split_Heap
  2746. ...
  2747. { Memory allocation }
  2748. ...
  2749. { !! non-volatile memory needed !!}
  2750. Switch_To_Base_Heap;
  2751. getmem (P,size);
  2752. Switch_To_Temp_Heap;
  2753. ...
  2754. {Memory allocation}
  2755. ...
  2756. ReleaseTempHeap;
  2757. {All allocated memory is now freed, except for the memory pointed to by 'P' }
  2758. ...
  2759. \end{verbatim}
  2760. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2761. % Debugging the heap
  2762. \subsection{Debugging the heap}
  2763. \fpc provides a unit that allows you to trace allocation and deallocation
  2764. of heap memory: \file{heaptrc}.
  2765. If you specify the \var{-gh} switch on the command-line, or if you include
  2766. \var{heaptrc} as the first unit in your uses clause, the memory manager
  2767. will trace what is allocated and deallocated, and on exit of your program,
  2768. a summary will be sent to standard output.
  2769. More information on using the \var{heaptrc} mechanism can be found in the
  2770. \userref and \unitsref.
  2771. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2772. % Writing your own memory manager.
  2773. \subsection{Writing your own memory manager}
  2774. \fpc allows you to write and use your own memory manager. The standard
  2775. functions \var{GetMem}, \var{FreeMem}, \var{ReallocMem} and \var{Maxavail}
  2776. use a special record in the system unit to do the actual memory management.
  2777. The system unit initializes this record with the system unit's own memory
  2778. manager, but you can read and set this record using the
  2779. \var{GetMemoryManager} and \var{SetMemoryManager} calls:
  2780. \begin{verbatim}
  2781. procedure GetMemoryManager(var MemMgr: TMemoryManager);
  2782. procedure SetMemoryManager(const MemMgr: TMemoryManager);
  2783. \end{verbatim}
  2784. the \var{TMemoryManager} record is defined as follows:
  2785. \begin{verbatim}
  2786. TMemoryManager = record
  2787. Getmem : Function(Size:Longint):Pointer;
  2788. Freemem : Function(var p:pointer):Longint;
  2789. FreememSize : Function(var p:pointer;Size:Longint):Longint;
  2790. AllocMem : Function(Size:longint):Pointer;
  2791. ReAllocMem : Function(var p:pointer;Size:longint):Pointer;
  2792. MemSize : function(p:pointer):Longint;
  2793. MemAvail : Function:Longint;
  2794. MaxAvail : Function:Longint;
  2795. HeapSize : Function:Longint;
  2796. end;
  2797. \end{verbatim}
  2798. As you can see, the elements of this record are procedural variables.
  2799. The system unit does nothing but call these various variables when you
  2800. allocate or deallocate memory.
  2801. Each of these functions corresponds to the corresponding call in the system
  2802. unit. We'll describe each one of them:
  2803. \begin{description}
  2804. \item[Getmem] This function allocates a new block on the heap. The block
  2805. should be \var{Size} bytes long. The return value is a pointer to the newly
  2806. allocated block.
  2807. \item[Freemem] should release a previously allocated block. The pointer
  2808. \var{P} points to a previously allocated block. The Memory manager should
  2809. implement a mechanism to determine what the size of the memory block is
  2810. \footnote{By storing it's size at a negative offset for instance.} The
  2811. return value is optional, and can be used to return the size of the freed
  2812. memory.
  2813. \item[FreememSize] This function should release the memory pointed to by
  2814. \var{P}. The argument \var{Size} is the expected size of the memory block
  2815. pointed to by P. This should be disregarded, but can be used to check the
  2816. behaviour of the program.
  2817. \item[AllocMem] Is the same as getmem, only the allocated memory should
  2818. be filled with zeroes before the call returns.
  2819. \item[ReAllocMem] Should allocate a memory block \var{Size} bytes large,
  2820. and should fill it with the contents of the memory block pointed to by
  2821. \var{P}, truncating this to the new size of needed. After that, the memory
  2822. pointed to by P may be deallocated. The return value is a pointer to the
  2823. new memory block.
  2824. \item[MemSize] should return the total amount of memory available for
  2825. allocation. This function may return zero if the memory manager does not
  2826. allow to determine this information.
  2827. \item[MaxAvail] should return the size of the largest block of memory that
  2828. is still available for allocation. This function may return zero if the
  2829. memory manager does not allow to determine this information.
  2830. \item[HeapSize] should return the total size of the heap. This may be zero
  2831. is the memory manager does not allow to determine this information.
  2832. \end{description}
  2833. To implement your own memory manager, it is sufficient to construct such a
  2834. record and to issue a call to \var{SetMemoryManager}.
  2835. To avoid conflicts with the system memory manager, setting the memory
  2836. manager should happen as soon as possible in the initialization of your
  2837. program, i.e. before any call to \var{getmem} is processed.
  2838. This means in practice that the unit implementing the memory manager should
  2839. be the first in the \var{uses} clause of your program or library, since it
  2840. will then be initialized before all other units (except of the system unit)
  2841. This also means that it is not possible to use the \file{heaptrc} unit in
  2842. combination with a custom memory manager, since the \file{heaptrc} unit uses
  2843. the system memory manager to do all it's allocation. Putting the
  2844. \file{heaptrc} unit after the unit implementing the memory manager would
  2845. overwrite the memory manager record installed by the custom memory manager,
  2846. and vice versa.
  2847. The following unit shows a straightforward implementation of a custom
  2848. memory manager using the memory manager of the \var{C} library. It is
  2849. distributed as a package with \fpc.
  2850. \begin{verbatim}
  2851. unit cmem;
  2852. {$mode objfpc}
  2853. interface
  2854. Function Malloc (Size : Longint) : Pointer;cdecl;
  2855. external 'c' name 'malloc';
  2856. Procedure Free (P : pointer); cdecl; external 'c' name 'free';
  2857. Procedure FreeMem (P : Pointer); cdecl; external 'c' name 'free';
  2858. function ReAlloc (P : Pointer; Size : longint) : pointer; cdecl;
  2859. external 'c' name 'realloc';
  2860. Function CAlloc (unitSize,UnitCount : Longint) : pointer;cdecl;
  2861. external 'c' name 'calloc';
  2862. implementation
  2863. Function CGetMem (Size : Longint) : Pointer;
  2864. begin
  2865. result:=Malloc(Size);
  2866. end;
  2867. Function CFreeMem (Var P : pointer) : Longint;
  2868. begin
  2869. Free(P);
  2870. Result:=0;
  2871. end;
  2872. Function CFreeMemSize(var p:pointer;Size:Longint):Longint;
  2873. begin
  2874. Result:=CFreeMem(P);
  2875. end;
  2876. Function CAllocMem(Size : Longint) : Pointer;
  2877. begin
  2878. Result:=calloc(Size,1);
  2879. end;
  2880. Function CReAllocMem (var p:pointer;Size:longint):Pointer;
  2881. begin
  2882. Result:=realloc(p,size);
  2883. end;
  2884. Function CMemSize (p:pointer): Longint;
  2885. begin
  2886. Result:=0;
  2887. end;
  2888. Function CMemAvail : Longint;
  2889. begin
  2890. Result:=0;
  2891. end;
  2892. Function CMaxAvail: Longint;
  2893. begin
  2894. Result:=0;
  2895. end;
  2896. Function CHeapSize : Longint;
  2897. begin
  2898. Result:=0;
  2899. end;
  2900. Const
  2901. CMemoryManager : TMemoryManager =
  2902. (
  2903. GetMem : CGetmem;
  2904. FreeMem : CFreeMem;
  2905. FreememSize : CFreememSize;
  2906. AllocMem : CAllocMem;
  2907. ReallocMem : CReAllocMem;
  2908. MemSize : CMemSize;
  2909. MemAvail : CMemAvail;
  2910. MaxAvail : MaxAvail;
  2911. HeapSize : CHeapSize;
  2912. );
  2913. Var
  2914. OldMemoryManager : TMemoryManager;
  2915. Initialization
  2916. GetMemoryManager (OldMemoryManager);
  2917. SetMemoryManager (CmemoryManager);
  2918. Finalization
  2919. SetMemoryManager (OldMemoryManager);
  2920. end.
  2921. \end{verbatim}
  2922. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2923. % Accessing DOS memory under the GO32 extender
  2924. \section{Using \dos memory under the Go32 extender}
  2925. \label{se:AccessingDosMemory}
  2926. Because \fpc is a 32 bit compiler, and uses a \dos extender, accessing DOS
  2927. memory isn't trivial. What follows is an attempt to an explanation of how to
  2928. access and use \dos or real mode memory\footnote{Thanks to an explanation of
  2929. Thomas schatzl (E-mail:\var{tom\_at\[email protected]}).}.
  2930. In {\em Proteced Mode}, memory is accessed through {\em Selectors} and
  2931. {\em Offsets}. You can think of Selectors as the protected mode
  2932. equivalents of segments.
  2933. In \fpc, a pointer is an offset into the \var{DS} selector, which points to
  2934. the Data of your program.
  2935. To access the (real mode) \dos memory, somehow you need a selector that
  2936. points to the \dos memory.
  2937. The \file{GO32} unit provides you with such a selector: The
  2938. \var{DosMemSelector} variable, as it is conveniently called.
  2939. You can also allocate memory in \dos's memory space, using the
  2940. \var{global\_dos\_alloc} function of the \file{GO32} unit.
  2941. This function will allocate memory in a place where \dos sees it.
  2942. As an example, here is a function that returns memory in real mode \dos and
  2943. returns a selector:offset pair for it.
  2944. \begin{verbatim}
  2945. procedure dosalloc(var selector : word;
  2946. var segment : word;
  2947. size : longint);
  2948. var result : longint;
  2949. begin
  2950. result := global_dos_alloc(size);
  2951. selector := word(result);
  2952. segment := word(result shr 16);
  2953. end;
  2954. \end{verbatim}
  2955. (You need to free this memory using the \var{global\_dos\_free} function.)
  2956. You can access any place in memory using a selector. You can get a selector
  2957. using the \var{allocate\_ldt\_descriptor} function, and then let this selector
  2958. point to the physical memory you want using the
  2959. \var{set\_segment\_base\_address} function, and set its length using
  2960. \var{set\_segment\_limit} function.
  2961. You can manipulate the memory pointed to by the selector using the functions
  2962. of the GO32 unit. For instance with the \var{seg\_fillchar} function.
  2963. After using the selector, you must free it again using the
  2964. \var{free\_ldt\_selector} function.
  2965. More information on all this can be found in the \unitsref, the chapter on
  2966. the \file{GO32} unit.
  2967. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2968. % Resource strings
  2969. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2970. \chapter{Resource strings}
  2971. \label{resourcestrings}
  2972. \section{Introduction}
  2973. Resource strings primarily exist to make internationalization of
  2974. applications easier, by introducing a language construct that provides
  2975. a uniform way of handling constant strings.
  2976. Most applications communicate with the user through some messages on the
  2977. graphical screen or console. Storing these messages in special constants
  2978. allows to store them in a uniform way in separate files, which can be used
  2979. for translation. A programmers interface exists to manipulate the actual
  2980. values of the constant strings at runtime, and a utility tool comes with the
  2981. Free Pascal compiler to convert the resource string files to whatever format
  2982. is wanted by the programmer. Both these things are discussed in the
  2983. following sections.
  2984. \section{The resource string file}
  2985. When a unit is compiled that contains a \var{resourcestring} section,
  2986. the compiler does 2 things:
  2987. \begin{enumerate}
  2988. \item It generates a table that contains the value of the strings as it
  2989. is declared in the sources.
  2990. \item It generates a {\em resource string file} that contains the names
  2991. of all strings, together with their declared values.
  2992. \end{enumerate}
  2993. This approach has 2 advantages: first of all, the value of the string is
  2994. always present in the program. If the programmer doesn't care to translate
  2995. the strings, the default values are always present in the binary. This also
  2996. avoids having to provide a file containing the strings. Secondly, having all
  2997. strings together in a compiler generated file ensures that all strings are
  2998. together (you can have multiple resourcestring sections in 1 unit or program)
  2999. and having this file in a fixed format, allows the programmer to choose his
  3000. way of internationalization.
  3001. For each unit that is compiled and that contains a resourcestring section,
  3002. the compiler generates a file that has the name of the unit, and an
  3003. extension \file{.rst}. The format of this file is as follows:
  3004. \begin{enumerate}
  3005. \item An empty line.
  3006. \item A line starting with a hash sign (\var{\#}) and the hash value of the
  3007. string, preceded by the text \var{hash value =}.
  3008. \item A third line, containing the name of the resource string in the format
  3009. \var{unitname.constantname}, all lowercase, followed by an equal sign, and
  3010. the string value, in a format equal to the pascal representation of this
  3011. string. The line may be continued on the next line, in that case it reads as
  3012. a pascal string expression with a plus sign in it.
  3013. \item Another empty line.
  3014. \end{enumerate}
  3015. If the unit contains no \var{resourcestring} section, no file is generated.
  3016. For example, the following unit:
  3017. \begin{verbatim}
  3018. unit rsdemo;
  3019. {$mode delphi}
  3020. {$H+}
  3021. interface
  3022. resourcestring
  3023. First = 'First';
  3024. Second = 'A Second very long string that should cover more than 1 line';
  3025. implementation
  3026. end.
  3027. \end{verbatim}
  3028. Will result in the following resource string file:
  3029. \begin{verbatim}
  3030. # hash value = 5048740
  3031. rsdemo.first='First'
  3032. # hash value = 171989989
  3033. rsdemo.second='A Second very long string that should cover more than 1 li'+
  3034. 'ne'
  3035. \end{verbatim}
  3036. The hash value is calculated with the function \var{Hash}. It is present in
  3037. the \file{objpas} unit. The value is the same value that the GNU gettext
  3038. mechanism uses. It is in no way unique, and can only be used to speed up
  3039. searches.
  3040. The \file{rstconv} utility that comes with the \fpc compiler allows to
  3041. manipulate these resource string files. At the moment, it can only be used
  3042. to make a \file{.po} file that can be fed to the GNU \file{msgfmt} program.
  3043. If someone wishes to have another format (Win32 resource files spring to
  3044. mind) he/she can enhance the \file{rstconv} program so it can generate
  3045. other types of files as well. GNU gettext was chosen because it is available
  3046. on all platforms, and is already widely used in the \var{Unix} and free
  3047. software community. Since the \fpc team doesn't want to restrict the use
  3048. of resource strings, the \file{.rst} format was chosen to provide a neutral
  3049. method, not restricted to any tool.
  3050. If you use resource strings in your units, and you want people to be able to
  3051. translate the strings, you must provide the resource string file. Currently,
  3052. there is no way to extract them from the unit file, though this is in
  3053. principle possible. It is not required to do this, the program can be
  3054. compiled without it, but then the translation of the strings isn't possible.
  3055. \section{Updating the string tables}
  3056. Having compiled a program with resourcestrings is not enough to
  3057. internationalize your program. At run-time, the program must initialize
  3058. the string tables with the correct values for the anguage that the user
  3059. selected. By default no such initialization is performed. All strings
  3060. are initialized with their declared values.
  3061. The \file{objpas} unit provides the mechanism to correctly initialize
  3062. the string tables. There is no need to include this unit in a \var{uses}
  3063. clause, since it is automatically loaded when a program or unit is
  3064. compiled in \var{Delphi} or \var{objfpc} mode. Since this is required
  3065. to use resource strings, the unit is always loaded when needed.
  3066. The resource strings are stored in tables, one per unit, and one for the
  3067. program, if it contains a \var{resourcestring} section as well. Each
  3068. resourcestring is stored with it's name, hash value, default value, and
  3069. the current value, all as \var{AnsiStrings}.
  3070. The objpas unit offers methods to retrieve the number of resourcestring
  3071. tables, the number of strings per table, and the above information for each
  3072. string. It also offers a method to set the current value of the strings.
  3073. Here are the declarations of all the functions:
  3074. \begin{verbatim}
  3075. Function ResourceStringTableCount : Longint;
  3076. Function ResourceStringCount(TableIndex : longint) : longint;
  3077. Function GetResourceStringName(TableIndex,
  3078. StringIndex : Longint) : Ansistring;
  3079. Function GetResourceStringHash(TableIndex,
  3080. StringIndex : Longint) : Longint;
  3081. Function GetResourceStringDefaultValue(TableIndex,
  3082. StringIndex : Longint) : AnsiString;
  3083. Function GetResourceStringCurrentValue(TableIndex,
  3084. StringIndex : Longint) : AnsiString;
  3085. Function SetResourceStringValue(TableIndex,
  3086. StringIndex : longint;
  3087. Value : Ansistring) : Boolean;
  3088. Procedure SetResourceStrings (SetFunction : TResourceIterator);
  3089. \end{verbatim}
  3090. Two other function exist, for convenience only:
  3091. \begin{verbatim}
  3092. Function Hash(S : AnsiString) : longint;
  3093. Procedure ResetResourceTables;
  3094. \end{verbatim}
  3095. Here is a short explanation of what each function does. A more detailed
  3096. explanation of the functions can be found in the \refref.
  3097. \begin{description}
  3098. \item[ResourceStringTableCount] returns the number of resource string tables
  3099. in the program.
  3100. \item[ResourceStringCount] returns the number of resource string entries in
  3101. a given table (tables are denoted by a zero-based index).
  3102. \item[GetResourceStringName] returns the name of a resource string in a
  3103. resource table. This is the name of the unit, a dot (.) and the name of
  3104. the string constant, all in lowercase. The strings are denoted by index,
  3105. also zero-based.
  3106. \item[GetResourceStringHash] returns the hash value of a resource string, as
  3107. calculated by the compiler with the \var{Hash} function.
  3108. \item[GetResourceStringDefaultValue] returns the default value of a resource
  3109. string, i.e. the value that appears in the resource string declaration, and
  3110. that is stored in the binary.
  3111. \item[GetResourceStringCurrentValue] returns the current value of a resource
  3112. string, i.e. the value set by the initialization (the default value), or the
  3113. value set by some previous internationalization routine.
  3114. \item[SetResourceStringValue] sets the current value of a resource string.
  3115. This function must be called to initialize all strings.
  3116. \item[SetResourceStrings] giving this function a callback will cause the
  3117. calback to be called for all resource strings, one by one, and set the value
  3118. of the string to the return value of the callback.
  3119. \end{description}
  3120. Two other functions exist, for convenience only:
  3121. \begin{description}
  3122. \item [Hash] can be used to calculate the hash value of a string. The hash
  3123. value stored in the tables is the result of this function, applied on the
  3124. default value. That value is calculated at compile time by the compiler.
  3125. \item[ResetResourceTables] will reset all the resource strings to their
  3126. default values. It is called by the initialization code of the objpas unit.
  3127. \end{description}
  3128. Given some \var{Translate} function, the following code would initialize
  3129. all resource strings:
  3130. \begin{verbatim}
  3131. Var I,J : Longint;
  3132. S : AnsiString;
  3133. begin
  3134. For I:=0 to ResourceStringTableCount-1 do
  3135. For J:=0 to ResourceStringCount(i)-1 do
  3136. begin
  3137. S:=Translate(GetResourceStringDefaultValue(I,J));
  3138. SetResourceStringValue(I,J,S);
  3139. end;
  3140. end;
  3141. \end{verbatim}
  3142. Other methods are of course possible, and the \var{Translate} function
  3143. can be implemented in a variety of ways.
  3144. \section{GNU gettext}
  3145. The unit \file{gettext} provides a way to internationalize an application
  3146. with the GNU \file{gettext} utilities. This unit is supplied with the
  3147. Free Component Library (FCL). it can be used as follows:
  3148. for a given application, the following steps must be followed:
  3149. \begin{enumerate}
  3150. \item Collect all resource string files and concatenate them together.
  3151. \item Invoke the \file{rstconv} program with the file resulting out of step
  3152. 1, resulting in a single \file{.po} file containing all resource strings of
  3153. the program.
  3154. \item Translate the \file{.po} file of step 2 in all required languages.
  3155. \item Run the \file{msgfmt} formatting program on all the \file{.po} files,
  3156. resulting in a set of \file{.mo} files, which can be distributed with your
  3157. application.
  3158. \item Call the \file{gettext} unit's \var{TranslateReosurceStrings} method,
  3159. giving it a template for the location of the \file{.mo} files, e.g. as in
  3160. \begin{verbatim}
  3161. TranslateResourcestrings('intl/restest.%s.mo');
  3162. \end{verbatim}
  3163. the \var{\%s} specifier will be replaced by the contents of the \var{LANG}
  3164. environment variable. This call should happen at program startup.
  3165. \end{enumerate}
  3166. An example program exists in the FCL sources, in the \file{fcl/tests}
  3167. directory.
  3168. \section{Caveat}
  3169. In principle it is possible to translate all resource strings at any time in
  3170. a running program. However, this change is not communicated to other
  3171. strings; its change is noticed only when a constant string is being used.
  3172. Consider the following example:
  3173. \begin{verbatim}
  3174. Const
  3175. help = 'With a little help of a programmer.';
  3176. Var
  3177. A : AnsiString;
  3178. begin
  3179. { lots of code }
  3180. A:=Help;
  3181. { Again some code}
  3182. TranslateStrings;
  3183. { More code }
  3184. \end{verbatim}
  3185. After the call to \var{TranslateStrings}, the value of \var{A} will remain
  3186. unchanged. This means that the assignment \var{A:=Help} must be executed
  3187. again in order for the change to become visible. This is important,
  3188. especially for GUI programs which have e.g. a menu. In order for the
  3189. change in resource strings to become visible, the new values must be
  3190. reloaded by program code into the menus...
  3191. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3192. % Optimizations done in the compiler
  3193. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3194. \chapter{Optimizations}
  3195. \section{ Non processor specific }
  3196. The following sections describe the general optimizations
  3197. done by the compiler, they are not processor specific. Some
  3198. of these require some compiler switch override while others are done
  3199. automatically (those which require a switch will be noted as such).
  3200. \subsection{ Constant folding }
  3201. In \fpc, if the operand(s) of an operator are constants, they
  3202. will be evaluated at compile time.
  3203. Example
  3204. \begin{verbatim}
  3205. x:=1+2+3+6+5;
  3206. will generate the same code as
  3207. x:=17;
  3208. \end{verbatim}
  3209. Furthermore, if an array index is a constant, the offset will
  3210. be evaluated at compile time. This means that accessing MyData[5]
  3211. is as efficient as accessing a normal variable.
  3212. Finally, calling \var{Chr}, \var{Hi}, \var{Lo}, \var{Ord}, \var{Pred},
  3213. or \var{Succ} functions with constant parameters generates no
  3214. run-time library calls, instead, the values are evaluated at
  3215. compile time.
  3216. \subsection{ Constant merging }
  3217. Using the same constant string two or more times generates only
  3218. one copy of the string constant.
  3219. \subsection{ Short cut evaluation }
  3220. Evaluation of boolean expression stops as soon as the result is
  3221. known, which makes code execute faster then if all boolean operands
  3222. were evaluated.
  3223. \subsection{ Constant set inlining }
  3224. Using the \var{in} operator is always more efficient then using the
  3225. equivalent \verb|<>|, \verb|=|, \verb|<=|, \verb|>=|, \verb|<| and \verb|>|
  3226. operators. This is because range comparisons can be done more easily with
  3227. \var{in} then with normal comparison operators.
  3228. \subsection{ Small sets }
  3229. Sets which contain less then 33 elements can be directly encoded
  3230. using a 32-bit value, therefore no run-time library calls to
  3231. evaluate operands on these sets are required; they are directly encoded
  3232. by the code generator.
  3233. \subsection{ Range checking }
  3234. Assignments of constants to variables are range checked at compile
  3235. time, which removes the need of the generation of runtime range checking
  3236. code.
  3237. \begin{remark}
  3238. This feature was not implemented before version 0.99.5 of \fpc.
  3239. \end{remark}
  3240. \subsection{ Shifts instead of multiply or divide }
  3241. When one of the operands in a multiplication is a power of
  3242. two, they are encoded using arithmetic shift instructions,
  3243. which generates more efficient code.
  3244. Similarly, if the divisor in a \var{div} operation is a power
  3245. of two, it is encoded using arithmetic shift instructions.
  3246. The same is true when accessing array indexes which are
  3247. powers of two, the address is calculated using arithmetic
  3248. shifts instead of the multiply instruction.
  3249. \subsection{ Automatic alignment }
  3250. By default all variables larger then a byte are guaranteed to be aligned
  3251. at least on a word boundary.
  3252. Furthermore all pointers allocated using the standard runtime
  3253. library (\var{New} and \var{GetMem} among others) are guaranteed
  3254. to return pointers aligned on a quadword boundary (64-bit alignment).
  3255. Alignment of variables on the stack depends on the target processor.
  3256. \begin{remark}
  3257. Two facts about alignment:
  3258. \begin{enumerate}
  3259. \item Quadword alignment of pointers is not guaranteed
  3260. on systems which don't use an internal heap, such as for the Win32
  3261. target.
  3262. \item Alignment is also done \emph{between} fields in
  3263. records, objects and classes, this is \emph{not} the same as
  3264. in Turbo Pascal and may cause problems when using disk I/O with these
  3265. types. To get no alignment between fields use the \var{packed} directive
  3266. or the \var{\{\$PackRecords n\}} switch. For further information, take a
  3267. look at the reference manual under the \var{record} heading.
  3268. \end{enumerate}
  3269. \end{remark}
  3270. \subsection{Smart linking}
  3271. This feature removes all unreferenced code in the final executable
  3272. file, making the executable file much smaller.
  3273. Smart linking is switched on with the \var{-Cx} command-line switch, or
  3274. using the \var{\{\$SMARTLINK ON\}} global directive.
  3275. \begin{remark}
  3276. Smart linking was implemented starting with version 0.99.6 of \fpc.
  3277. \end{remark}
  3278. \subsection{ Inline routines }
  3279. The following runtime library routines are coded directly into the
  3280. final executable : \var{Lo}, \var{Hi}, \var{High}, \var{Sizeof},
  3281. \var{TypeOf}, \var{Length}, \var{Pred}, \var{Succ}, \var{Inc},
  3282. \var{Dec} and \var{Assigned}.
  3283. \begin{remark} Inline \var{Inc} and \var{Dec} were not completely
  3284. implemented until version 0.99.6 of \fpc.
  3285. \end{remark}
  3286. \subsection{ Case optimization }
  3287. When using the \var{-O1} (or higher) switch, case statements will be
  3288. generated using a jump table if appropriate, to make them execute
  3289. faster.
  3290. \subsection{ Stack frame omission }
  3291. Under specific conditions, the stack frame (entry and exit code for
  3292. the routine, see section \ref{se:Calling}) will be omitted, and the
  3293. variable will directly be accessed via the stack pointer.
  3294. Conditions for omission of the stack frame :
  3295. \begin{itemize}
  3296. \item The function has no parameters nor local variables.
  3297. \item Routine does not call other routines.
  3298. \item Routine does not contain assembler statements. However,
  3299. a \var{assembler} routine may omit it's stack frame.
  3300. \item Routine is not declared using the \var{Interrupt} directive.
  3301. \item Routine is not a constructor or destructor.
  3302. \end{itemize}
  3303. \subsection{ Register variables }
  3304. When using the \var{-Or} switch, local variables or parameters
  3305. which are used very often will be moved to registers for faster
  3306. access.
  3307. \begin{remark}
  3308. Register variable allocation is currently an experimental feature,
  3309. and should be used with caution.
  3310. \end{remark}
  3311. \subsection{ Intel x86 specific }
  3312. Here follows a listing of the optimizing techniques used in the compiler:
  3313. \begin{enumerate}
  3314. \item When optimizing for a specific Processor (\var{-Op1, -Op2, -Op3},
  3315. the following is done:
  3316. \begin{itemize}
  3317. \item In \var{case} statements, a check is done whether a jump table
  3318. or a sequence of conditional jumps should be used for optimal performance.
  3319. \item Determines a number of strategies when doing peephole optimization, e.g.:
  3320. \var{movzbl (\%ebp), \%eax} will be changed into
  3321. \var{xorl \%eax,\%eax; movb (\%ebp),\%al } for Pentium and PentiumMMX.
  3322. \end{itemize}
  3323. \item When optimizing for speed (\var{-OG}, the default) or size (\var{-Og}), a choice is
  3324. made between using shorter instructions (for size) such as \var{enter \$4},
  3325. or longer instructions \var{subl \$4,\%esp} for speed. When smaller size is
  3326. requested, things aren't aligned on 4-byte boundaries. When speed is
  3327. requested, things are aligned on 4-byte boundaries as much as possible.
  3328. \item Fast optimizations (\var{-O1}): activate the peephole optimizer
  3329. \item Slower optimizations (\var{-O2}): also activate the common subexpression
  3330. elimination (formerly called the "reloading optimizer")
  3331. \item Uncertain optimizations (\var{-Ou}): With this switch, the common subexpression
  3332. elimination algorithm can be forced into making uncertain optimizations.
  3333. Although you can enable uncertain optimizations in most cases, for people who
  3334. do not understand the following technical explanation, it might be the safest to
  3335. leave them off.
  3336. \begin{quote}
  3337. % Jonas's own words..
  3338. \em
  3339. If uncertain optimizations are enabled, the CSE algortihm assumes
  3340. that
  3341. \begin{itemize}
  3342. \item If something is written to a local/global register or a
  3343. procedure/function parameter, this value doesn't overwrite the value to
  3344. which a pointer points.
  3345. \item If something is written to memory pointed to by a pointer variable,
  3346. this value doesn't overwrite the value of a local/global variable or a
  3347. procedure/function parameter.
  3348. \end{itemize}
  3349. % end of quote
  3350. \end{quote}
  3351. The practical upshot of this is that you cannot use the uncertain
  3352. optimizations if you both write and read local or global variables directly and
  3353. through pointers (this includes \var{Var} parameters, as those are pointers too).
  3354. The following example will produce bad code when you switch on
  3355. uncertain optimizations:
  3356. \begin{verbatim}
  3357. Var temp: Longint;
  3358. Procedure Foo(Var Bar: Longint);
  3359. Begin
  3360. If (Bar = temp)
  3361. Then
  3362. Begin
  3363. Inc(Bar);
  3364. If (Bar <> temp) then Writeln('bug!')
  3365. End
  3366. End;
  3367. Begin
  3368. Foo(Temp);
  3369. End.
  3370. \end{verbatim}
  3371. The reason it produces bad code is because you access the global variable
  3372. \var{Temp} both through its name \var{Temp} and through a pointer, in this
  3373. case using the \var{Bar} variable parameter, which is nothing but a pointer
  3374. to \var{Temp} in the above code.
  3375. On the other hand, you can use the uncertain optimizations if
  3376. you access global/local variables or parameters through pointers,
  3377. and {\em only} access them through this pointer\footnote{
  3378. You can use multiple pointers to point to the same variable as well, that
  3379. doesn't matter.}.
  3380. For example:
  3381. \begin{verbatim}
  3382. Type TMyRec = Record
  3383. a, b: Longint;
  3384. End;
  3385. PMyRec = ^TMyRec;
  3386. TMyRecArray = Array [1..100000] of TMyRec;
  3387. PMyRecArray = ^TMyRecArray;
  3388. Var MyRecArrayPtr: PMyRecArray;
  3389. MyRecPtr: PMyRec;
  3390. Counter: Longint;
  3391. Begin
  3392. New(MyRecArrayPtr);
  3393. For Counter := 1 to 100000 Do
  3394. Begin
  3395. MyRecPtr := @MyRecArrayPtr^[Counter];
  3396. MyRecPtr^.a := Counter;
  3397. MyRecPtr^.b := Counter div 2;
  3398. End;
  3399. End.
  3400. \end{verbatim}
  3401. Will produce correct code, because the global variable \var{MyRecArrayPtr}
  3402. is not accessed directly, but only through a pointer (\var{MyRecPtr} in this
  3403. case).
  3404. In conclusion, one could say that you can use uncertain optimizations {\em
  3405. only} when you know what you're doing.
  3406. \end{enumerate}
  3407. \subsection{ Motorola 680x0 specific }
  3408. Using the \var{-O2} switch does several optimizations in the
  3409. code produced, the most notable being:
  3410. \begin{itemize}
  3411. \item Sign extension from byte to long will use \var{EXTB}
  3412. \item Returning of functions will use \var{RTD}
  3413. \item Range checking will generate no run-time calls
  3414. \item Multiplication will use the long \var{MULS} instruction, no
  3415. runtime library call will be generated
  3416. \item Division will use the long \var{DIVS} instruction, no
  3417. runtime library call will be generated
  3418. \end{itemize}
  3419. \section{Optimization switches}
  3420. This is where the various optimizing switches and their actions are
  3421. described, grouped per switch.
  3422. \begin{description}
  3423. \item [-On:\ ] with n = 1..3: these switches activate the optimizer.
  3424. A higher level automatically includes all lower levels.
  3425. \begin{itemize}
  3426. \item Level 1 (\var{-O1}) activates the peephole optimizer
  3427. (common instruction sequences are replaced by faster equivalents).
  3428. \item Level 2 (\var{-O2}) enables the assembler data flow analyzer,
  3429. which allows the common subexpression elimination procedure to
  3430. remove unnecessary reloads of registers with values they already contain.
  3431. \item Level 3 (\var{-O3}) enables uncertain optimizations. For more info, see -Ou.
  3432. \end{itemize}
  3433. \item[-OG:\ ]
  3434. This causes the code generator (and optimizer, IF activated), to favor
  3435. faster, but code-wise larger, instruction sequences (such as
  3436. "\verb|subl $4,%esp|") instead of slower, smaller instructions
  3437. ("\verb|enter $4|"). This is the default setting.
  3438. \item[-Og:\ ] This one is exactly the reverse of -OG, and as such these
  3439. switches are mutually exclusive: enabling one will disable the other.
  3440. \item[-Or:\ ] This setting (once it's fixed) causes the code generator to
  3441. check which variables are used most, so it can keep those in a register.
  3442. \item[-Opn:\ ] with n = 1..3: Setting the target processor does NOT
  3443. activate the optimizer. It merely influences the code generator and,
  3444. if activated, the optimizer:
  3445. \begin{itemize}
  3446. \item During the code generation process, this setting is used to
  3447. decide whether a jump table or a sequence of successive jumps provides
  3448. the best performance in a case statement.
  3449. \item The peephole optimizer takes a number of decisions based on this
  3450. setting, for example it translates certain complex instructions, such
  3451. as
  3452. \begin{verbatim}
  3453. movzbl (mem), %eax|
  3454. \end{verbatim}
  3455. to a combination of simpler instructions
  3456. \begin{verbatim}
  3457. xorl %eax, %eax
  3458. movb (mem), %al
  3459. \end{verbatim}
  3460. for the Pentium.
  3461. \end{itemize}
  3462. \item[-Ou:\ ] This enables uncertain optimizations. You cannot use these
  3463. always, however. The previous section explains when they can be used, and
  3464. when they cannot be used.
  3465. \end{description}
  3466. \section{Tips to get faster code}
  3467. Here, some general tips for getting better code are presented. They
  3468. mainly concern coding style.
  3469. \begin{itemize}
  3470. \item Find a better algorithm. No matter how much you and the compiler
  3471. tweak the code, a quicksort will (almost) always outperform a bubble
  3472. sort, for example.
  3473. \item Use variables of the native size of the processor you're writing
  3474. for. For the 80x86 and compatibles, this is 32 bit, so you're best of
  3475. using longint and cardinal variables.
  3476. \item Turn on the optimizer.
  3477. \item Write your if/then/else statements so that the code in the "then"-part
  3478. gets executed most of the time (improves the rate of successful jump prediction).
  3479. \item If you are allocating and disposing a lot of small memory blocks,
  3480. check out the heapblocks variable (heapblocks are on by default from
  3481. release 0.99.8 and later)
  3482. \item Profile your code (see the -pg switch) to find out where the
  3483. bottlenecks are. If you want, you can rewrite those parts in assembler.
  3484. You can take the code generated by the compiler as a starting point. When
  3485. given the \var{-a} command-line switch, the compiler will not erase the
  3486. assembler file at the end of the assembly process, so you can study the
  3487. assembler file.
  3488. {\em Note:} Code blocks which contain an assembler block, are not processed
  3489. at all by the optimizer at this time. Update: as of version 0.99.11,
  3490. the Pascal code surrounding the assembler blocks is optimized.
  3491. \end{itemize}
  3492. \section{ Floating point }
  3493. This is where can be found processor specific information on floating
  3494. point code generated by the compiler.
  3495. \subsection{ Intel x86 specific }
  3496. All normal floating point types map to their real type, including
  3497. \var{comp} and \var{extended}.
  3498. \subsection{ Motorola 680x0 specific }
  3499. Early generations of the Motorola 680x0 processors did not have integrated
  3500. floating point units, so to circumvent this fact, all floating point
  3501. operations are emulated (with the \var{\$E+} switch, which is the default)
  3502. using the IEEE \var{Single} floating point type. In other words when
  3503. emulation is on, Real, Single, Double and Extended all map to the
  3504. \var{single} floating point type.
  3505. When the \var{\$E} switch is turned off, normal 68882/68881/68040
  3506. floating point opcodes are emitted. The Real type still maps to
  3507. \var{Single} but the other types map to their true floating point
  3508. types. Only basic FPU opcodes are used, which means that it can
  3509. work on 68040 processors correctly.
  3510. \begin{remark} \var{Double} and \var{Extended} types in true floating
  3511. point mode have not been extensively tested as of version 0.99.5.
  3512. \end{remark}
  3513. \begin{remark}
  3514. The \var{comp} data type is currently not supported.
  3515. \end{remark}
  3516. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3517. % programming libraries
  3518. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3519. \chapter{Programming libraries}
  3520. \label{ch:libraries}
  3521. \section{Introduction}
  3522. \fpc supports the creation of shared libraries on \linux and \windows.
  3523. The mechanism is the same on both systems, although on \windows library
  3524. indexes can be used, which is not the case on \linux.
  3525. In the following sections we discuss how to create a library, and how
  3526. to use these libraries in programs.
  3527. \section{Creating a library}
  3528. Creation of libraries is supported in any mode of the \fpc compiler,
  3529. but it may be that the arguments or return values differ if the library is
  3530. compiled in 2 different modes.
  3531. A library can be created just as a program, only it uses the \var{library}
  3532. keyword, and it has an \var{exports} section. The following listing
  3533. demonstrates a simple library:
  3534. \FPCexample{subs}
  3535. The function \var{SubStr} does not have to be declared in the library file
  3536. itself. It can also be declared in the interface section of a unit that
  3537. is used by the library.
  3538. Compilation of this source will result in the creation of a library called
  3539. \file{libsubs.so} on \linux, or \file{subs.dll} on \windows. The compiler
  3540. will take care of any additional linking that is required to create a
  3541. shared library.
  3542. The library exports one function: \var{SubStr}. The case is important. The
  3543. case as it appears in the \var{exports} clause is used to export the
  3544. function.
  3545. Creation of libraries is supported in any mode of the \fpc compiler,
  3546. but it may be that the arguments or return values differ if the library is
  3547. compiled in 2 different modes. E.g. if your function expects an
  3548. \var{Integer} argument, then the library will expect different integer
  3549. sizes if you compile it in Delphi mode or in TP mode.
  3550. If you want your library to be called from C programs, it is important to
  3551. specify the C calling convention for the exported functions, with the
  3552. \var{cdecl} modifier. Since a C compiler doesn't know about the \fpc
  3553. calling conventions, your functions would be called incorrectly, resulting
  3554. in a corrupted stack.
  3555. On \windows, most libraries use the \var{stdcall} convention, so it may be
  3556. better to use that one if your library is to be used on \windows systems.
  3557. \section{Using a library in a pascal program}
  3558. In order to use a function that resides in a library, it is sufficient to
  3559. declare the function as it exists in the library as an \var{external}
  3560. function, with correct arguments and return type. The calling convention
  3561. used by the function should be declared correctly as well. The compiler
  3562. will then link the library as specified in the \var{external} statement
  3563. to your program\footnote{If you omit the library name in the \var{external}
  3564. modifier, then you can still tell the compiler to link to that library using
  3565. the \var{\{\$Linklib \}} directive.}.
  3566. For example, to use the library as defined above from a pascal program, you can use
  3567. the following pascal program:
  3568. \FPCexample{psubs}
  3569. As is shown in the example, you must declare the function as \var{external}.
  3570. Here also, it is necessary to specify the correct calling convention (it
  3571. should always match the convention as used by the function in the library),
  3572. and to use the correct casing for your declaration.
  3573. This program can be compiled without any additional command-switches,
  3574. and should run just like that, provided the library is placed where
  3575. the system can find it. On \linux, this is \file{/usr/lib} or any
  3576. directory listed in the \file{/etc/ld.so.conf} file. On \windows, this
  3577. can be the program directory, the Windows system directory, or any directoy
  3578. mentioned in the \var{PATH}.
  3579. Using the library in this way links the library to your program at compile
  3580. time. This means that
  3581. \begin{enumerate}
  3582. \item The library must be present on the system where the program is
  3583. compiled.
  3584. \item The library must be present on the system where the program is
  3585. executed.
  3586. \item Both libraries must be exactly the same.
  3587. \end{enumerate}
  3588. Or it may simply be that you don't know the name of the function to
  3589. be called, you just know the arguments it expects.
  3590. It is therefore also possible to load the library at run-time, store
  3591. the function address in a procedural variable, and use this procedural
  3592. variable to access the function in the library.
  3593. The following example demonstrates this technique:
  3594. \FPCexample{plsubs}
  3595. As in the case of compile-time linking, the crucial thing in this
  3596. listing is the declaration of the \var{TSubStrFunc} type.
  3597. It should match the declaration of the function you're trying to use.
  3598. Failure to specify a correct definition will result in a faulty stack or,
  3599. worse still, may cause your program to crash with an access violation.
  3600. \section{Using a pascal library from a C program}
  3601. \begin{remark}
  3602. The examples in this section assume a \linux system; similar commands
  3603. as the ones below exist for \windows, though.
  3604. \end{remark}
  3605. You can also call a \fpc generated library from a C program:
  3606. \Cexample{ctest}
  3607. To compile this example, the following command can be used:
  3608. \begin{verbatim}
  3609. gcc -o ctest ctest.c -lsubs
  3610. \end{verbatim}
  3611. provided the code is in \file{ctest.c}.
  3612. The library can also be loaded dynamically from C, as shown in the following
  3613. example:
  3614. \Cexample{ctest2}
  3615. This can be compiled using the following command:
  3616. \begin{verbatim}
  3617. gcc -o ctest2 ctest2.c -ldl
  3618. \end{verbatim}
  3619. \lstset{language=delphi}
  3620. The \var{-ldl} tells gcc that the program needs the \file{libdl.so} library
  3621. to load dynamical libraries.
  3622. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3623. % using resources
  3624. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3625. \chapter{Using Windows resources}
  3626. \label{ch:windres}
  3627. \section{The resource directive \var{\$R}}
  3628. Under \windows, you can include resources in your executable or library
  3629. using the \var{\{\$R filename\}} directive. These resources can then
  3630. be accessed through the standard windows API calls.
  3631. When the compiler encounters a resource directive, it just creates an
  3632. entry in the unit \file{.ppu} file; it doesn't link the resource. Only
  3633. when it creates a library or executable, it looks for all the resource
  3634. files for which it encountered a directive, and tries to link them in.
  3635. The default extension for resource files is \file{.res}. When the
  3636. filename has as the first character an asterix (\var{*}), the
  3637. compiler will replace the asterix with the name of the current unit,
  3638. library or program.
  3639. \begin{remark}
  3640. This means that the asterix may only be used after a \var{unit},
  3641. \var{library} or \var{program} clause.
  3642. \end{remark}
  3643. \section{Creating resources}
  3644. The \fpc compiler itself doesn't create any resource files; it just
  3645. compiles them into the executable. To create resource files, you
  3646. can use some GUI tools as the Borland resource workshop; but it is
  3647. also possible to use a windows resource compiler like \gnu
  3648. \file{windres}. \file{windres} comes with the \gnu binutils, but the
  3649. \fpc distribution also contains a version which you can use.
  3650. The usage of windres is straightforward; it reads an input file
  3651. describing the resources to create and outputs a resource file.
  3652. A typical invocation of \file{windres} would be
  3653. \begin{verbatim}
  3654. windres -i mystrings.rc -o mystrings.res
  3655. \end{verbatim}
  3656. this will read the \file{mystrings.rc} file and output a
  3657. \file{mystrings.res} resource file.
  3658. A complete overview of the windres tools is outside the scope of this
  3659. document, but here are some things you can use it for:
  3660. \begin{description}
  3661. \item[stringtables] that contain lists of strings.
  3662. \item[bitmaps] which are read from an external file.
  3663. \item[icons] which are also read from an external file.
  3664. \item[Version information] which can be viewed with the Windows
  3665. explorer.
  3666. \item[Menus] Can be designed as resources and used in your GUI
  3667. applications.
  3668. \item[Arbitrary data] Can be included as resources and read with the
  3669. windows API calls.
  3670. \end{description}
  3671. Some of these will be described below.
  3672. \section{Using string tables.}
  3673. String tables can be used to store and retrieve large collections of
  3674. strings in your application.
  3675. A string table looks as follows:
  3676. \begin{verbatim}
  3677. STRINGTABLE { 1, "hello World !"
  3678. 2, "hello world again !"
  3679. 3, "last hello world !" }
  3680. \end{verbatim}
  3681. You can compile this (we assume the file is called \file{tests.rc}) as
  3682. follows:
  3683. \begin{verbatim}
  3684. windres -i tests.rc -o tests.res
  3685. \end{verbatim}
  3686. And this is the way to retrieve the strings from your program:
  3687. \begin{verbatim}
  3688. program tests;
  3689. {$mode objfpc}
  3690. Uses Windows;
  3691. {$R *.res}
  3692. Function LoadResourceString (Index : longint): Shortstring;
  3693. begin
  3694. SetLength(Result,LoadString(FindResource(0,Nil,RT_STRING),Index,@Result[1],SizeOf(Result)))
  3695. end;
  3696. Var
  3697. I: longint;
  3698. begin
  3699. For i:=1 to 3 do
  3700. Writeln (Loadresourcestring(I));
  3701. end.
  3702. \end{verbatim}
  3703. The call to \var{FindResource} searches for the stringtable in the
  3704. compiled-in resources. The \var{LoadString} function then reads the
  3705. string with index \var{i} out of the table, and puts it in a buffer,
  3706. which can then be used. Both calls are in the windows unit.
  3707. \section{Inserting version information}
  3708. The win32 API allows to store version information in your binaries.
  3709. This information can be made visible with the \windows Explorer, by
  3710. right-clicking on the executable or library, and selecting the
  3711. 'Properties' menu. In the tab 'Version' the version information will
  3712. be displayed.
  3713. Here is how to insert version information in your binary:
  3714. \begin{verbatim}
  3715. 1 VERSIONINFO
  3716. FILEVERSION 4, 0, 3, 17
  3717. PRODUCTVERSION 3, 0, 0, 0
  3718. FILEFLAGSMASK 0
  3719. FILEOS 0x40000
  3720. FILETYPE 1
  3721. {
  3722. BLOCK "StringFileInfo"
  3723. {
  3724. BLOCK "040904E4"
  3725. {
  3726. VALUE "CompanyName", "Free Pascal"
  3727. VALUE "FileDescription", "Free Pascal version information extractor"
  3728. VALUE "FileVersion", "1.0"
  3729. VALUE "InternalName", "Showver"
  3730. VALUE "LegalCopyright", "GNU Public License"
  3731. VALUE "OriginalFilename", "showver.pp"
  3732. VALUE "ProductName", "Free Pascal"
  3733. VALUE "ProductVersion", "1.0"
  3734. }
  3735. }
  3736. }
  3737. \end{verbatim}
  3738. As you can see, you can insert various kinds of information in the version info
  3739. block. The keyword \var{VERSIONINFO} marks the beginning of the version
  3740. information resource block. The keywords \var{FILEVERSION},
  3741. \var{PRODUCTVERSION} give the actual file version, while the block
  3742. \var{StringFileInfo} gives other information that is displayed in the
  3743. explorer.
  3744. The Free Component Library comes with a unit (\file{fileinfo}) that allows
  3745. to extract and view version information in a straightforward and easy manner;
  3746. the demo program that comes with it (\file{showver}) shows version information
  3747. for an arbitrary executable or DLL.
  3748. \section{Inserting an application icon}
  3749. When \windows shows an executable in the Explorer, it looks for an icon
  3750. in the executable to show in front of the filename, the application
  3751. icon.
  3752. Inserting an application icon is very easy and can be done as follows
  3753. \begin{verbatim}
  3754. AppIcon ICON "filename.ico"
  3755. \end{verbatim}
  3756. This will read the file \file{filename.ico} and insert it in the
  3757. resource file.
  3758. \section{Using a pascal preprocessor}
  3759. Sometimes you want to use symbolic names in your resource file, and
  3760. use the same names in your program to access the resources. To accomplish
  3761. this, there exists a preprocessor for \file{windres} that understands pascal
  3762. syntax: \file{fprcp}. This preprocessor is shipped with the \fpc
  3763. distribution.
  3764. The idea is that the preprocessor reads a pascal unit that has some
  3765. symbolic constants defined in it, and replaces symbolic names in the
  3766. resource file by the values of the constants in the unit:
  3767. As an example: consider the follwoing unit:
  3768. \begin{verbatim}
  3769. unit myunit;
  3770. interface
  3771. Const
  3772. First = 1;
  3773. Second = 2:
  3774. Third = 3;
  3775. Implementation
  3776. end.
  3777. \end{verbatim}
  3778. And the following resource file:
  3779. \begin{verbatim}
  3780. #include "myunit.pp"
  3781. STRINGTABLE { First, "hello World !"
  3782. Second, "hello world again !"
  3783. Third, "last hello world !" }
  3784. \end{verbatim}
  3785. if you invoke windres with the \var{--preprocessor} option:
  3786. \begin{verbatim}
  3787. windres --preprocessor fprcp -i myunit.rc -o myunit.res
  3788. \end{verbatim}
  3789. Then the preprocessor will replace the symbolic names 'first', 'second'
  3790. and 'third' with their actual values.
  3791. In your program, you can then refer to the strings by their symbolic
  3792. names (the constants) instead of using a numeric index.
  3793. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3794. % Appendices
  3795. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3796. \appendix
  3797. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3798. % Appendix A
  3799. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3800. \chapter{Anatomy of a unit file}
  3801. \label{ch:AppA}
  3802. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3803. % Basics
  3804. \section{Basics}
  3805. The best and most updated documentation about the ppu files can be
  3806. found in \file{ppu.pas} and \file{ppudump.pp} which can be found in
  3807. \file{rtl/utils/}.
  3808. To read or write the ppufile, you can use the ppu unit \file{ppu.pas}
  3809. which has an object called tppufile which holds all routines that deal
  3810. with ppufile handling. While describing the layout of a ppufile, the
  3811. methods which can be used for it are presented as well.
  3812. A unit file consists of basically five or six parts:
  3813. \begin{enumerate}
  3814. \item A unit header.
  3815. \item A file interface part.
  3816. \item A definition part. Contains all type and procedure definitions.
  3817. \item A symbol part. Contains all symbol names and references to their
  3818. definitions.
  3819. \item A browser part. Contains all references from this unit to other
  3820. units and inside this unit. Only available when the \var{uf\_has\_browser} flag is
  3821. set in the unit flags
  3822. \item A file implementation part (currently unused).
  3823. \end{enumerate}
  3824. \section{reading ppufiles}
  3825. We will first create an object ppufile which will be used below. We are
  3826. opening unit \file{test.ppu} as an example.
  3827. \begin{verbatim}
  3828. var
  3829. ppufile : pppufile;
  3830. begin
  3831. { Initialize object }
  3832. ppufile:=new(pppufile,init('test.ppu');
  3833. { open the unit and read the header, returns false when it fails }
  3834. if not ppufile.open then
  3835. error('error opening unit test.ppu');
  3836. { here we can read the unit }
  3837. { close unit }
  3838. ppufile.close;
  3839. { release object }
  3840. dispose(ppufile,done);
  3841. end;
  3842. \end{verbatim}
  3843. Note: When a function fails (for example not enough bytes left in an
  3844. entry) it sets the \var{ppufile.error} variable.
  3845. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3846. % The Header
  3847. \section{The Header}
  3848. The header consists of a record containing 24 bytes:
  3849. \begin{verbatim}
  3850. tppuheader=packed record
  3851. id : array[1..3] of char; { = 'PPU' }
  3852. ver : array[1..3] of char;
  3853. compiler : word;
  3854. cpu : word;
  3855. target : word;
  3856. flags : longint;
  3857. size : longint; { size of the ppufile without header }
  3858. checksum : longint; { checksum for this ppufile }
  3859. end;
  3860. \end{verbatim}
  3861. The header is already read by the \var{ppufile.open} command.
  3862. You can access all fields using \var{ppufile.header} which holds
  3863. the current header record.
  3864. \begin{tabular}{lp{10cm}}
  3865. \raggedright
  3866. field & description \\ \hline
  3867. \var{id} &
  3868. this is allways 'PPU', can be checked with
  3869. \mbox{\var{function ppufile.CheckPPUId:boolean;}} \\
  3870. \var{ver} & ppu version, currently '015', can be checked with
  3871. \mbox{\var{function ppufile.GetPPUVersion:longint;}} (returns 15) \\
  3872. \var{compiler}
  3873. & compiler version used to create the unit. Doesn't contain the
  3874. patchlevel. Currently 0.99 where 0 is the high byte and 99 the
  3875. low byte \\
  3876. \var{cpu} & cpu for which this unit is created.
  3877. 0 = i386
  3878. 1 = m68k \\
  3879. \var{target} & target for which this unit is created, this depends also on the
  3880. cpu!
  3881. For i386:
  3882. \begin{tabular}[t]{ll}
  3883. 0 & Go32v1 \\
  3884. 1 & Go32V2 \\
  3885. 2 & Linux-i386 \\
  3886. 3 & OS/2 \\
  3887. 4 & Win32
  3888. \end{tabular}
  3889. For m68k:
  3890. \begin{tabular}[t]{ll}
  3891. 0 & Amiga \\
  3892. 1 & Mac68k \\
  3893. 2 & Atari \\
  3894. 3 & Linux-m68k
  3895. \end{tabular} \\
  3896. \var{flag} &
  3897. the unit flags, contains a combination of the uf\_ constants which
  3898. are definied in \file{ppu.pas} \\
  3899. \var{size} & size of this unit without this header \\
  3900. \var{checksum} &
  3901. checksum of the interface parts of this unit, which determine if
  3902. a unit is changed or not, so other units can see if they need to
  3903. be recompiled
  3904. \\ \hline
  3905. \end{tabular}
  3906. % The sections
  3907. \section{The sections}
  3908. After this header follow the sections. All sections work the same!
  3909. A section consists of entries and ends also with an entry, but
  3910. containing the specific \var{ibend} constant (see \file{ppu.pas} for a list
  3911. of constants).
  3912. Each entry starts with an entryheader.
  3913. \begin{verbatim}
  3914. tppuentry=packed record
  3915. id : byte;
  3916. nr : byte;
  3917. size : longint;
  3918. end;
  3919. \end{verbatim}
  3920. \begin{tabular}{lp{10cm}}
  3921. field & Description \\ \hline
  3922. id & this is 1 or 2 and can be checked to see whether the entry is correctly
  3923. found. 1 means its a main entry, which says that it is part of the
  3924. basic layout as explained before. 2 means that it it a sub entry
  3925. of a record or object. \\
  3926. nr & contains the ib constant number which determines what kind of
  3927. entry it is. \\
  3928. size & size of this entry without the header, can be used to skip entries
  3929. very easily. \\ \hline
  3930. \end{tabular}
  3931. To read an entry you can simply call \var{ppufile.readentry:byte},
  3932. it returns the
  3933. \var{tppuentry.nr} field, which holds the type of the entry.
  3934. A common way how this works is (example is for the symbols):
  3935. \begin{verbatim}
  3936. repeat
  3937. b:=ppufile.readentry;
  3938. case b of
  3939. ib<etc> : begin
  3940. end;
  3941. ibendsyms : break;
  3942. end;
  3943. until false;
  3944. \end{verbatim}
  3945. Then you can parse each entry type yourself. \var{ppufile.readentry} will take
  3946. care of skipping unread bytes in the entry and reads the next entry
  3947. correctly! A special function is \var{skipuntilentry(untilb:byte):boolean;}
  3948. which will read the ppufile until it finds entry \var{untilb} in the main
  3949. entries.
  3950. Parsing an entry can be done with \var{ppufile.getxxx} functions. The
  3951. available functions are:
  3952. \begin{verbatim}
  3953. procedure ppufile.getdata(var b;len:longint);
  3954. function getbyte:byte;
  3955. function getword:word;
  3956. function getlongint:longint;
  3957. function getreal:ppureal;
  3958. function getstring:string;
  3959. \end{verbatim}
  3960. To check if you're at the end of an entry you can use the following
  3961. function:
  3962. \begin{verbatim}
  3963. function EndOfEntry:boolean;
  3964. \end{verbatim}
  3965. {\em notes:}
  3966. \begin{enumerate}
  3967. \item \var{ppureal} is the best real that exists for the cpu where the
  3968. unit is created for. Currently it is \var{extended} for i386 and
  3969. \var{single} for m68k.
  3970. \item the \var{ibobjectdef} and \var{ibrecorddef} have stored a definition
  3971. and symbol section for themselves. So you'll need a recursive call. See
  3972. \file{ppudump.pp} for a correct implementation.
  3973. \end{enumerate}
  3974. A complete list of entries and what their fields contain can be found
  3975. in \file{ppudump.pp}.
  3976. \section{Creating ppufiles}
  3977. Creating a new ppufile works almost the same as reading one.
  3978. First you need to init the object and call create:
  3979. \begin{verbatim}
  3980. ppufile:=new(pppufile,init('output.ppu'));
  3981. ppufile.create;
  3982. \end{verbatim}
  3983. After that you can simply write all needed entries. You'll have to take
  3984. care that you write at least the basic entries for the sections:
  3985. \begin{verbatim}
  3986. ibendinterface
  3987. ibenddefs
  3988. ibendsyms
  3989. ibendbrowser (only when you've set uf_has_browser!)
  3990. ibendimplementation
  3991. ibend
  3992. \end{verbatim}
  3993. Writing an entry is a little different than reading it. You need to first
  3994. put everything in the entry with ppufile.putxxx:
  3995. \begin{verbatim}
  3996. procedure putdata(var b;len:longint);
  3997. procedure putbyte(b:byte);
  3998. procedure putword(w:word);
  3999. procedure putlongint(l:longint);
  4000. procedure putreal(d:ppureal);
  4001. procedure putstring(s:string);
  4002. \end{verbatim}
  4003. After putting all the things in the entry you need to call
  4004. \var{ppufile.writeentry(ibnr:byte)} where \var{ibnr} is the entry number
  4005. you're writing.
  4006. At the end of the file you need to call \var{ppufile.writeheader} to write the
  4007. new header to the file. This takes automatically care of the new size of the
  4008. ppufile. When that is also done you can call \var{ppufile.close} and dispose the
  4009. object.
  4010. Extra functions/variables available for writing are:
  4011. \begin{verbatim}
  4012. ppufile.NewHeader;
  4013. ppufile.NewEntry;
  4014. \end{verbatim}
  4015. This will give you a clean header or entry. Normally this is called
  4016. automatically in \var{ppufile.writeentry}, so there should be no need to
  4017. call these methods.
  4018. \begin{verbatim}
  4019. ppufile.flush;
  4020. \end{verbatim}
  4021. to flush the current buffers to the disk
  4022. \begin{verbatim}
  4023. ppufile.do_crc:boolean;
  4024. \end{verbatim}
  4025. set to false if you don't want that the crc is updated, this is necessary
  4026. if you write for example the browser data.
  4027. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4028. % Appendix B
  4029. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4030. \chapter{Compiler and RTL source tree structure}
  4031. \label{ch:AppB}
  4032. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4033. % The compiler source tree
  4034. \section{The compiler source tree}
  4035. All compiler source files are in one directory, normally in
  4036. \file{source/compiler}. For more informations
  4037. about the structure of the compiler have a look at the
  4038. Compiler Manual which contains also some informations about
  4039. compiler internals.
  4040. The \file{compiler} directory contains a subdirectory \var{utils},
  4041. which contains mainly the utilities for creation and maintainance of the
  4042. message files.
  4043. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4044. % The compiler source tree
  4045. \section{The RTL source tree}
  4046. The RTL source tree is divided in many subdirectories, but is very
  4047. structured and easy to understand. It mainly consists of three parts:
  4048. \begin{enumerate}
  4049. \item A OS-dependent directory. This contains the files that are different for
  4050. each operating system. When compiling the RTL, you should do it here. The
  4051. following directories exist:
  4052. \begin{itemize}
  4053. \item \file{atari} for the atari. Not maintained any more.
  4054. \item \file{amiga} for the amiga. Not maintained any more.
  4055. \item \file{go32v1} For \dos, using the GO32v1 extender. Not maintained any
  4056. more.
  4057. \item \file{go32v2} For \dos, using the GO32v2 extender.
  4058. \item \file{linux} for \linux platforms. It has two subdirect
  4059. \item \file{os2} for \ostwo.
  4060. \item \file{win32} for Win32 platforms.
  4061. \end{itemize}
  4062. \item A processor dependent directory. This contains files that are system
  4063. independent, but processor dependent. It contains mostly optimized routines
  4064. for a specific processor. The following directories exist:
  4065. \begin{itemize}
  4066. \item \file{i386} for the Intel series of processors.
  4067. \item \file{m68k} for the motorola m68000 series of processors.
  4068. \end{itemize}
  4069. \item An OS-independent and Processor independent directory: \file{inc}. This
  4070. contains complete units, and include files containing interface parts of
  4071. units.
  4072. \end{enumerate}
  4073. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4074. % Appendix C
  4075. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4076. \chapter{Compiler limits}
  4077. \label{ch:AppC}
  4078. Although many of the restrictions imposed by the MS-DOS system are removed
  4079. by use of an extender, or use of another operating system, there still are
  4080. some limitations to the compiler:
  4081. \begin{enumerate}
  4082. \item Procedure or Function definitions can be nested to a level of 32.
  4083. \item Maximally 255 units can be used in a program when using the real-mode
  4084. compiler (i.e. a binary that was compiled by Borland Pascal). When using the 32-bit compiler, the limit is set to 1024. You can
  4085. change this by redefining the \var{maxunits} constant in the
  4086. \file{files.pas} compiler source file.
  4087. \end{enumerate}
  4088. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4089. % Appendix D
  4090. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4091. \chapter{Compiler modes}
  4092. \label{ch:AppD}
  4093. Here we list the exact effect of the different compiler modes. They can be
  4094. set with the \var{\$Mode} switch, or by command line switches.
  4095. \section{FPC mode}
  4096. This mode is selected by the \var{{\$MODE FPC}} switch. On the command-line,
  4097. this means that you use none of the other compatibility mode switches.
  4098. It is the default mode of the compiler. This means essentially:
  4099. \begin{enumerate}
  4100. \item You must use the address operator to assign procedural variables.
  4101. \item A forward declaration must be repeated exactly the same by the
  4102. implementation of a function/procedure. In particular, you can not omit the
  4103. parameters when implementing the function or procedure.
  4104. \item Overloading of functions is allowed.
  4105. \item Nested comments are allowed.
  4106. \item The Objpas unit is NOT loaded.
  4107. \item You can use the cvar type.
  4108. \item PChars are converted to strings automatically.
  4109. \end{enumerate}
  4110. \section{TP mode}
  4111. This mode is selected by the \var{{\$MODE TP}} switch. On the command-line,
  4112. this mode is selected by the \var{-So} switch.
  4113. \begin{enumerate}
  4114. \item You cannot use the address operator to assign procedural variables.
  4115. \item A forward declaration must not be repeated exactly the same by the
  4116. implementation of a function/procedure. In particular, you can omit the
  4117. parameters when implementing the function or procedure.
  4118. \item Overloading of functions is not allowed.
  4119. \item The Objpas unit is NOT loaded.
  4120. \item Nested comments are not allowed.
  4121. \item You can not use the cvar type.
  4122. \end{enumerate}
  4123. \section{Delphi mode}
  4124. This mode is selected by the \var{{\$MODE DELPHI}} switch. On the command-line,
  4125. this mode is selected by the \var{-Sd} switch.
  4126. \begin{enumerate}
  4127. \item You can not use the address operator to assign procedural variables.
  4128. \item A forward declaration must not be repeated exactly the same by the
  4129. implementation of a function/procedure. In particular, you not omit the
  4130. parameters when implementing the function or procedure.
  4131. \item Overloading of functions is not allowed.
  4132. \item Nested comments are not allowed.
  4133. \item The Objpas unit is loaded right after the system unit. One of the
  4134. consequences of this is that the type \var{Integer} is redefined as
  4135. \var{Longint}.
  4136. \end{enumerate}
  4137. \section{GPC mode}
  4138. This mode is selected by the \var{{\$MODE GPC}} switch. On the command-line,
  4139. this mode is selected by the \var{-Sp} switch.
  4140. \begin{enumerate}
  4141. \item You must use the address operator to assign procedural variables.
  4142. \item A forward declaration must not be repeated exactly the same by the
  4143. implementation of a function/procedure. In particular, you can omit the
  4144. parameters when implementing the function or procedure.
  4145. \item Overloading of functions is not allowed.
  4146. \item The Objpas unit is NOT loaded.
  4147. \item Nested comments are not allowed.
  4148. \item You can not use the cvar type.
  4149. \end{enumerate}
  4150. \section{OBJFPC mode}
  4151. This mode is selected by the \var{{\$MODE OBJFPC}} switch. On the command-line,
  4152. this mode is selected by the \var{-S2} switch.
  4153. \begin{enumerate}
  4154. \item You must use the address operator to assign procedural variables.
  4155. \item A forward declaration must be repeated exactly the same by the
  4156. implementation of a function/procedure. In particular, you can not omit the
  4157. parameters when implementing the function or procedure.
  4158. \item Overloading of functions is allowed.
  4159. \item Nested comments are allowed.
  4160. \item The Objpas unit is loaded right after the system unit. One of the
  4161. consequences of this is that the type \var{Integer} is redefined as
  4162. \var{Longint}.
  4163. \item You can use the cvar type.
  4164. \item PChars are converted to strings automatically.
  4165. \end{enumerate}
  4166. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4167. % Appendix E
  4168. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4169. \chapter{Using \file{fpcmake}}
  4170. \label{ch:makefile}
  4171. \newcommand{\mvar}[1]{\var{\$(#1)}}
  4172. \section{Introduction}
  4173. \fpc comes with a special makefile tool, \file{fpcmake}, which can be
  4174. used to construct a \file{Makefile} for use with \gnu \file{make}.
  4175. All sources from the \fpc team are compiled with this system.
  4176. \file{fpcmake} uses a file \file{Makefile.fpc} and constructs a file
  4177. \file{Makefile} from it, based on the settings in \file{Makefile.fpc}.
  4178. The following sections explain what settings can be set in \file{Makefile.fpc},
  4179. what variables are set by \var{fpcmake}, what variables it expects to be set,
  4180. and what targets it defines. After that, some settings in the resulting
  4181. \file{Makefile} are explained.
  4182. \section{Usage}
  4183. \file {fpcmake} reads a \file{Makefile.fpc} and converts it to a
  4184. \file{Makefile} suitable for reading by \gnu \file{make}
  4185. to compile your projects. It is similar in functionality to GNU
  4186. \file{configure} or \file{Imake} for making X projects.
  4187. \file{fpcmake} accepts filenames of makefile description files
  4188. as it's command-line arguments. For each of these files it will
  4189. create a \file{Makefile} in the same directory where the file is
  4190. located, overwriting any existing file with that name.
  4191. If no options are given, it just attempts to read the file
  4192. \file{Makefile.fpc} in the current directory and tries to
  4193. construct a \file{Makefile} from it. any previously existing
  4194. \file{Makefile} will be erased.
  4195. % Makefile.fpc format.
  4196. \section{Format of the configuration file}
  4197. This section describes the rules that can be present in the file
  4198. that is fed to \file{fpcmake}.
  4199. The file \file{Makefile.fpc} is a plain ASCII file that contains
  4200. a number of pre-defined sections as in a \windows \file{.ini}-file,
  4201. or a Samba configuration file.
  4202. They look more or less as follows:
  4203. \begin{verbatim}
  4204. [targets]
  4205. units=mysql_com mysql_version mysql
  4206. examples=testdb
  4207. [dirs]
  4208. fpcdir=../..
  4209. [rules]
  4210. mysql$(PPUEXT): mysql$(PASEXT) mysql_com$(PPUEXT)
  4211. testdb$(EXEEXT): testdb$(PASEXT) mysql$(PPUEXT)
  4212. \end{verbatim}
  4213. The following sections are recognized (in alphabetical order):
  4214. \subsection{Clean}
  4215. Specifies rules for cleaning the directory of units and programs.
  4216. The following entries are recognized:
  4217. \begin{description}
  4218. \item[units] names of all units that should be removed when cleaning.
  4219. Don't specify extensions, the makefile will append these by itself.
  4220. \item[files] names of files that should be removed. Specify full filenames.
  4221. \end{description}
  4222. \subsection{Defaults}
  4223. The \var{defaults} section contains some default settings. The following keywords
  4224. are recognized:
  4225. \begin{description}
  4226. \item[defaultdir]
  4227. \item[defaultbuilddir]
  4228. \item[defaultinstalldir]
  4229. \item[defaultzipinstalldir]
  4230. \item[defaultcleandir]
  4231. \item[defaultrule] Specifies the default rule to execute. \file{fpcmake}
  4232. will make sure that this rule is executed if make is executed without
  4233. arguments, i.e., without an explicit target.
  4234. \item[defaulttarget]
  4235. Specifies the default operating system target for which the \file{Makefile}
  4236. should compile the units and programs. By default this is determined from
  4237. the default compiler target.
  4238. \item[defaultcpu]
  4239. Specifies the default target processor for which the \file{Makefile}
  4240. should compile the units and programs. By default this is determined from
  4241. the default compiler processor.
  4242. \end{description}
  4243. \subsection{Dirs}
  4244. In this section you can specify the location of several directories
  4245. which the \file{Makefile} could need for compiling other packages or for finding
  4246. the units.
  4247. The following keywords are recognised:
  4248. \begin{description}
  4249. \item[fpcdir]
  4250. Specifies the directory where all the \fpc source trees reside. Below this
  4251. directory the \file{Makefile} expects to find the \file{rtl}, \file{fcl} and
  4252. \file{packages} directory trees.
  4253. \item[packagedir]
  4254. Specifies the directory where all the package source directories are. By
  4255. default this equals \mvar{FPCDIR}\var{/packages}.
  4256. \item[toolkitdir]
  4257. Specifies the directory where toolkit source directories are.
  4258. \item[componentdir]
  4259. Specifies the directory where component source directories are.
  4260. \item[unitdir]
  4261. A colon-separated list of directories that must be added to the unit
  4262. search path of the compiler.
  4263. \item[libdir]
  4264. A colon-separated list of directories that must be added to the library
  4265. search path of the compiler.
  4266. \item[objdir]
  4267. A colon-separated list of directories that must be added to the object file
  4268. search path of the compiler.
  4269. \item[targetdir]
  4270. Specifies the directory where the compiled programs should go.
  4271. \item[sourcesdir]
  4272. A space separated list of directories where sources can reside.
  4273. This will be used for the \var{vpath} setting of \gnu \file{make}.
  4274. \item[unittargetdir]
  4275. Specifies the directory where the compiled units should go.
  4276. \item[incdir]
  4277. A colon-separated list of directories that must be added to the include file
  4278. search path of the compiler.
  4279. \end{description}
  4280. \subsection{Info}
  4281. This section can be used to customize the information generating
  4282. targets that \file{fpcmake} generates. It is simply a series of boolean
  4283. values that specify whether a certain part of the \var{info} target will be
  4284. generated. The following keywords are recognised:
  4285. \begin{description}
  4286. \item[infoconfig]
  4287. Specifies whether configuration info should be shown. By default this is
  4288. \var{True}.
  4289. \item[infodirs]
  4290. Specifies whether a list of subdirectories to be treated will be shown. By
  4291. degault this is \var{False}.
  4292. \item[infotools]
  4293. Specifies whether a list of tools that are used by the makefile will be
  4294. shown. By default this is \var{False}.
  4295. \item[infoinstall]
  4296. Specifies whether the installation rules will be shown. By default this is
  4297. \var{True}.
  4298. \item[infoobjects]
  4299. Specifies whether the \file{Makefile} objects will be shown, i.e. a list of
  4300. all units and programs that will be built by \file{make}.
  4301. \end{description}
  4302. \subsection{Install}
  4303. Contains instructions for installation of your units and programs. The
  4304. following keywords are recognized:
  4305. \begin{description}
  4306. \item[dirprefix] is the directory below wchich all installs are done.
  4307. This corresponds to the \var{--prefix} argument to \gnu \file{configure}.
  4308. It is used for the installation of programs and units. By default, this is
  4309. \file{/usr} on \linux, and \file{/pp} on all other platforms.
  4310. \item[dirbase]
  4311. The directory that is used as the base directory for the installation of
  4312. units. Default this is \var{dirprefix} appended with \var{/lib/fpc/FPC\_VERSION}
  4313. for \linux or simply the \var{dirprefix} on other platforms.
  4314. \end{description}
  4315. Units will be installed in the subdirectory \file{units/\$(OS\_TARGET)}
  4316. of the \var{dirbase} entry.
  4317. \subsection{Libs}
  4318. This section specifies what units should be merged into a library, and what
  4319. external libraries are needed. It can contain the following keywords:
  4320. \begin{description}
  4321. \item[libname] the name of the library that should be created.
  4322. \item[libunits] a comma-separated list of units that should be moved into
  4323. one library.
  4324. \item[needgcclib] a boolean value that specifies whether the \file{gcc}
  4325. library is needed. This will make sure that the path to the GCC library
  4326. is inserted in the library search path.
  4327. \item[needotherlib]
  4328. (\linux only) a boolean value that tells the makefile that it should add
  4329. all library directories from the \file{ld.so.conf} file to the compiler
  4330. command-line.
  4331. \end{description}
  4332. \subsection{Packages}
  4333. Which packages must be used. This section can contain the following keywords:
  4334. \begin{description}
  4335. \item[packages]
  4336. A comma-separated list of packages that are needed to compile the targets.
  4337. Valid for all platforms. In order to differentiate between platforms, you
  4338. can prepend the keyword \var{packages} with the OS you are compiling for,
  4339. e.g. \var{linuxpackages} if you want the makefile to use the listed
  4340. packages on linux only.
  4341. \item[fcl] This is a boolean value (0 or 1) that indicates whether the FCL is used.
  4342. \item[rtl]
  4343. This is a boolean value (0 or 1) that indicates whether the RTL should be
  4344. recompiled.
  4345. \end{description}
  4346. \subsection{Postsettings}
  4347. Anything that is in this section will be inserted as-is in the makefile
  4348. \textit{after} the makefile rules that are generated by fpcmake, but
  4349. \textit{before} the general configuration rules.
  4350. In this section, you cannot use variables that are defined by fpcmake rules, but you
  4351. can define additional rules and configuration variables.
  4352. \subsection{Presettings}
  4353. Anything that is in this section will be inserted as-is in the makefile
  4354. \textit{before} the makefile target rules that are generated by fpcmake.
  4355. This means that you cannot use any variables that are normally defined by
  4356. fpcmake rules.
  4357. \subsection{Rules}
  4358. In this section you can insert dependency rules and any other targets
  4359. you wish to have. Do not insert 'default rules' here.
  4360. \subsection{Sections}
  4361. Here you can specify which 'rule sections' should be included in the
  4362. \file{Makefile}.
  4363. The sections consist of a series of boolean keywords; each keyword decies
  4364. whether a particular section will be written to the makefile. By default,
  4365. all sections are written.
  4366. You can have the following boolean keywords in this section.
  4367. \begin{description}
  4368. \item[none]
  4369. If this is set to true, then no sections are written.
  4370. \item[units]
  4371. If set to \var{False}, \file{fpcmake} omits the rules for compiling units.
  4372. \item[exes]
  4373. If set to \var{False}, \file{fpcmake} omits the rules for compiling executables.
  4374. \item[loaders]
  4375. If set to \var{False}, \file{fpcmake} omits the rules for assembling assembler files.
  4376. \item[examples]
  4377. If set to \var{False}, \file{fpcmake} omits the rules for compiling examples.
  4378. \item[package]
  4379. If set to \var{False}, \file{fpcmake} omits the rules for making packages.
  4380. \item[compile]
  4381. If set to \var{False}, \file{fpcmake} omits the generic rules for compiling pascal files.
  4382. \item[depend]
  4383. If set to \var{False}, \file{fpcmake} omits the dependency rules.
  4384. \item[install]
  4385. If set to \var{False}, \file{fpcmake} omits the rules for installing everything.
  4386. \item[sourceinstall]
  4387. If set to \var{False}, \file{fpcmake} omits the rules for installing the sources.
  4388. \item[zipinstall]
  4389. If set to \var{False}, \file{fpcmake} omits the rules for installing archives.
  4390. \item[clean]
  4391. If set to \var{False}, \file{fpcmake} omits the rules for cleaning the directories.
  4392. \item[libs]
  4393. If set to \var{False}, \file{fpcmake} omits the rules for making libraries.
  4394. \item[command]
  4395. If set to \var{False}, \file{fpcmake} omits the rules for composing the command-line based on the various
  4396. variables.
  4397. \item[exts]
  4398. If set to \var{False}, \file{fpcmake} omits the rules for making libraries.
  4399. \item[dirs]
  4400. If set to \var{False}, \file{fpcmake} omits the rules for running make in subdirectories..
  4401. \item[tools]
  4402. If set to \var{False}, \file{fpcmake} omits the rules for running some tools as the erchiver, UPX and zip.
  4403. \item[info]
  4404. If set to \var{False}, \file{fpcmake} omits the rules for generating information.
  4405. \end{description}
  4406. \subsection{Targets}
  4407. In this section you can define the various targets. The following keywords
  4408. can be used there:
  4409. \begin{description}
  4410. \item[dirs]
  4411. A space separated list of directories where make should also be run.
  4412. \item[examples]
  4413. A space separated list of example programs that need to be compiled when
  4414. the user asks to compile the examples. Do not specify an extension,
  4415. the extension will be appended.
  4416. \item[loaders]
  4417. A space separated list of names of assembler files that must be assembled.
  4418. Don't specify the extension, the extension will be appended.
  4419. \item[programs]
  4420. A space separated list of program names that need to be compiled. Do not
  4421. specify an extension, the extension will be appended.
  4422. \item[rst] a list of \file{rst} files that needs to be converted to \file{.po}
  4423. files for use with \gnu \file{gettext} and internationalization routines.
  4424. \item[units]
  4425. A space separated list of unit names that need to be compiled. Do not
  4426. specify an extension, just the name of the unit as it would appear un a
  4427. \var{uses} clause is sufficient.
  4428. \end{description}
  4429. \subsection{Tools}
  4430. In this section you can specify which tools are needed. Definitions to
  4431. use each of the listed tools will be inserted in the makefile, depending
  4432. on the setting in this section.
  4433. Each keyword is a boolean keyword; you can switch the use of a tool on or
  4434. off with it.
  4435. The following keywords are recognised:
  4436. \begin{description}
  4437. \item[toolppdep]
  4438. Use \file{ppdep}, the dependency tool. \var{True} by default.
  4439. \item[toolppumove]
  4440. Use \file{ppumove}, the Free Pascal unit mover. \var{True} by default.
  4441. \item[toolppufiles]
  4442. Use the \file{ppufile} tool to determine dependencies of unit files.
  4443. \var{True} by default.
  4444. \item[toolsed]
  4445. Use \file{sed} the stream line editor. \var{False} by default.
  4446. \item[tooldata2inc]
  4447. Use the \file{data2inc} tool to create include files from data files.
  4448. \var{False} by default.
  4449. \item[tooldiff]
  4450. Use the \gnu \file{diff} tool. \var{False} by default.
  4451. \item[toolcmp]
  4452. Use the \file{cmp} file comparer tool. \var{False} by default.
  4453. \item[toolupx]
  4454. Use the \file{upx} executable packer.\var{True} by default.
  4455. \item[tooldate]
  4456. use the \file{date} date displaying tool. \var{True} by default.
  4457. \item[toolzip]
  4458. Use the \file{zip} file archiver. This is used by the zip targets.
  4459. \var{True} by default.
  4460. \end{description}
  4461. \subsection{Zip}
  4462. This section can be used to make zip files from the compiled units and
  4463. programs. By default all compiled units are zipped. The zip behaviour can
  4464. be influenced with the presettings and postsettings sections.
  4465. The following keywords can be used in this unit:
  4466. \begin{description}
  4467. \item[zipname]
  4468. this file is the name of the zip file that will be produced.
  4469. \item[ziptarget]
  4470. is the name of a makefile target that will be executed before the zip is
  4471. made. By default this is the \var{install} target.
  4472. \end{description}
  4473. \section{Programs needed to use the generated makefile}
  4474. The following programs are needed by the generated \file{Makefile}
  4475. to function correctly:
  4476. \begin{description}
  4477. \item[cp] a copy program.
  4478. \item[date] a program that prints the date.
  4479. \item[install] a program to install files.
  4480. \item[make] the \file{make} program, obviously.
  4481. \item[pwd] a program that prints the current working directory.
  4482. \item[rm] a program to delete files.
  4483. \end{description}
  4484. These are standard programs on linux systems, with the possible exception of
  4485. \file{make}. For \dos or \windowsnt, they can be found in the
  4486. file \file{gnuutils.zip} on the \fpc FTP site.
  4487. The following programs are optionally needed if you use some special targets.
  4488. Which ones you need are controlled by the settings in the \var{tools} section.
  4489. \begin{description}
  4490. \item[cmp] a \dos and \windowsnt file comparer. Used if \var{toolcmp} is \var{True}.
  4491. \item[diff] a file comparer. Used if \var{tooldiff} is \var{True}.
  4492. \item[ppdep] the ppdep depency lister. Used if \var{toolppdep} is \var{True}.
  4493. Distributed with \fpc.
  4494. \item[ppufiles] the ppufiles unit file dependency lister. Used if \var{toolppufiles}
  4495. is \var{True}. Distributed with \fpc.
  4496. \item[ppumove] the \fpc unit mover. Used if \var{toolppumove} is \var{True}.
  4497. Distributed with \fpc.
  4498. \item[sed] the \file{sed} program. Used if \var{toolsed} is \var{True}.
  4499. \item[upx] the UPX executable packer. Used if \var{toolupx} is \var{True}.
  4500. \item[zip] the zip archiver program. Used if \var{toolzip} is \var{True}.
  4501. \end{description}
  4502. All of these can also be found on the \fpc FTP site for \dos and \windowsnt.
  4503. \file{ppdep,ppufiles} and \file{ppumove} are distributed with the \fpc
  4504. compiler.
  4505. %
  4506. \section{Variables that affect the generated makefile}
  4507. The makefile generated by \file{fpcmake} contains a lot of variables.
  4508. Some of them are set in the makefile itself, others can be set and are taken
  4509. into account when set.
  4510. These variables can be split in several groups:
  4511. \begin{itemize}
  4512. \item Environment variables.
  4513. \item Directory variables.
  4514. \item Compiler command-line variables.
  4515. \end{itemize}
  4516. Each group will be discussed separately.
  4517. \subsection{Environment variables}
  4518. In principle, \var{fpcmake} doesn't expect any environment variable to be set.
  4519. Optionally, you can set the variable \var{FPCMAKEINI} which should contain
  4520. the name of a file with the basic rules that \file{fpcmake} will generate.
  4521. By default, \file{fpcmake} has a compiled-in copy of \file{fpcmake.ini},
  4522. which contains the basic rules, so there should be no need to set this variable.
  4523. You can set it however, if you wish to change the way in which fpcmake works and
  4524. creates rules.
  4525. The initial \file{fpcmake.ini} file can be found in the \file{utils} source
  4526. package on the \fpc ftp site.
  4527. \subsection{Directory variables}
  4528. The first set of variables controls the directories that are
  4529. recognised in the makefile. They should not be set in the
  4530. \file{Makefile.fpc} file, but can be specified on the commandline.
  4531. \begin{description}
  4532. \item[INCDIR] this is a list of directories, separated by spaces, that will
  4533. be added as include directories to the compiler command-line. Each
  4534. directory in the list is prepended with \var{-I} and added to the
  4535. compiler options.
  4536. \item[LIBDIR] is a list of library paths, separated by spaces. Each
  4537. directory in the list is prepended with \var{-Fl} and added to the
  4538. compiler options.
  4539. \item[OBJDIR] is a list of object file directories, separated by spaces, that is
  4540. added to the object files path, i.e. Each directory in the list is prepended with
  4541. \var{-Fo}.
  4542. \end{description}
  4543. \subsection{Compiler command-line variables }
  4544. The following variable can be set on the \file{make} command-line,
  4545. they will be recognised and integrated in the compiler command-line:
  4546. \begin{description}
  4547. \item[OPT] Any options that you want to pass to the compiler. The contents
  4548. of \var{OPT} is simply added to the compiler command-line.
  4549. \item[OPTDEF] Are optional defines, added to the command-line of the
  4550. compiler. They do not get \var{-d} prepended.
  4551. \end{description}
  4552. \section{Variables set by \file{fpcmake}}
  4553. All of the following variables are only set by \file{fpcmake}, if
  4554. they aren't already defined. This means that you can override them by
  4555. setting them on the make commandline, or setting them in the \var{presettings}
  4556. section. But most of them are correctly determined by the generated
  4557. \file{Makefile} or set by your settings in the configuration file.
  4558. The following sets of variables are defined:
  4559. \begin{itemize}
  4560. \item Directory variables.
  4561. \item Program names.
  4562. \item File extensions.
  4563. \item Target files.
  4564. \end{itemize}
  4565. Each of these sets is discussed in the subsequent:
  4566. \subsection{Directory variables}
  4567. The following directories are defined by the makefile:
  4568. \begin{description}
  4569. \item[BASEDIR] is set to the current directory if the \file{pwd} command is
  4570. available. If not, it is set to '.'.
  4571. \item[BASEINSTALLDIR] is the base for all directories where units are
  4572. installed. By default, On \linux, this is set to
  4573. \mvar{PREFIXINSTALLDIR}\var{/lib/fpc/}\mvar{RELEASEVER}.\\ On other systems,
  4574. it is set to \mvar{PREFIXINSTALLDIR}. You can also set it with the
  4575. \var{basedir} variable in the \var{Install} section.
  4576. \item[BININSTALLDIR] is set to \mvar{BASEINSTALLDIR}/\var{bin} on \linux,
  4577. and\\ \mvar{BASEINSTALLDIR}/\var{bin}/\mvar{OS\_TARGET} on other systems.
  4578. This is the place where binaries are installed.
  4579. \item[GCCLIBDIR] (\linux only) is set to the directory where \file{libgcc.a}
  4580. is. If \var{needgcclib} is set to \var{True} in the \var{Libs} section, then
  4581. this directory is added to the compiler commandline with \var{-Fl}.
  4582. \item[LIBINSTALLDIR] is set to \mvar{BASEINSTALLDIR} on \linux,\\
  4583. and \mvar{BASEINSTALLDIR}/\var{lib} on other systems.
  4584. \item[NEEDINCDIR] is a space-separated list of library paths. Each
  4585. directory in the list is prepended with \var{-Fl} and added to the
  4586. compiler options. Set by the \var{incdir} keyword in the \var{Dirs} section.
  4587. \item[NEEDLIBDIR] is a space-separated list of library paths. Each
  4588. directory in the list is
  4589. prepended with \var{-Fl} and added to the compiler options.
  4590. Set by the \var{libdir} keyword in the \var{Dirs} section.
  4591. \item[NEEDOBJDIR] is a list of object file directories, separated by
  4592. spaces. Each directory in the list is prepended with \var{-Fo} and
  4593. added to the compiler options.
  4594. Set by the \var{objdir} keyword in the \var{Dirs} section.
  4595. \item[NEEDUNITDIR] is a list of unit directories, separated by spaces.
  4596. Each directory in the list is prepended with \var{-Fu} and is added to the
  4597. compiler options.
  4598. Set by the \var{unitdir} keyword in the \var{Dirs} section.
  4599. \item[TARGETDIR] This directory is added as the output directory of
  4600. the compiler, where all units and executables are written, i.e. it gets
  4601. \var{-FE} prepended. It is set by the \var{targtdir} keyword in the
  4602. \var{Dirs} section.
  4603. \item[TARGETUNITDIR] If set, this directory is added as the output directory of
  4604. the compiler, where all units and executables are written, i.e. it gets
  4605. \var{-FU} prepended.It is set by the \var{targtdir} keyword in the
  4606. \var{Dirs} section.
  4607. \item[PREFIXINSTALLDIR] is set to \file{/usr} on \linux, \file{/pp} on \dos
  4608. or \windowsnt. Set by the \var{dirprefix} keyword in the \var{Install}
  4609. section.
  4610. \item[UNITINSTALLDIR] is where units will be installed. This is set to\\
  4611. \mvar{BASEINSTALLDIR}/\mvar{UNITPREFIX} \\
  4612. on \linux. On other systems, it is set to \\
  4613. \mvar{BASEINSTALLDIR}/\mvar{UNITPREFIX}/\mvar{OS\_TARGET}.
  4614. \end{description}
  4615. \subsection{Target variables}
  4616. The second set of variables controls the targets that are constructed
  4617. by the makefile. They are created by \file{fpcmake}, so you can use
  4618. them in your rules, but you shouldn't assign values to them yourself.
  4619. \begin{description}
  4620. \item[EXEOBJECTS] This is a list of executable names that will be compiled.
  4621. the makefile appends \mvar{EXEEXT} to these names. It is set by the
  4622. \var{programs} keyword in the \var{Targets} section.
  4623. \item[LOADEROBJECTS] is a list of space-separated names that identify
  4624. loaders to be compiled. This is mainly used in the compiler's RTL sources.
  4625. It is set by the \var{loaders} keyword in the \var{Targets} section.
  4626. \item[UNITOBJECTS] This is a list of unit names that will be compiled. The
  4627. makefile appends \mvar{PPUEXT} to each of these names to form the unit file
  4628. name. The sourcename is formed by adding \mvar{PASEXT}.
  4629. It is set by the \var{units} keyword in the \var{Targets} section.
  4630. \item[ZIPNAME] is the name of the archive that will be created by the
  4631. makefile.
  4632. It is set by the \var{zipname} keyword in the \var{Zip} section.
  4633. \item[ZIPTARGET] is the target that is built before the archive is made.
  4634. this target is built first. If successful, the zip archive will be made.
  4635. It is set by the \var{ziptarget} keyword in the \var{Zip} section.
  4636. \end{description}
  4637. \subsection{Compiler command-line variables}
  4638. The following variables control the compiler command-line:
  4639. \begin{description}
  4640. \item[CPU\_SOURCE] the target CPU type is added as a define to the compiler
  4641. command line. This is determined by the Makefile itself.
  4642. \item[CPU\_TARGET] the target CPU type is added as a define to the compiler
  4643. command line. This is determined by the Makefile itself.
  4644. \item[LIBNAME] if a shared library is requested this is the name of the
  4645. shared library to produce. Don't add \var{lib} to this, the compiler will
  4646. do that.
  4647. It is set by the \var{libname} keyword in the \var{Libs} section.
  4648. \item[NEEDGCCLIB] if this variable is defined, then the path to \file{libgcc}
  4649. is added to the library path.
  4650. It is set by the \var{needgcclib} keyword in the \var{Libs} section.
  4651. \item[NEEDOTHERLIB] (\linux only) If this is defined, then the makefile will
  4652. append all directories that appear in \var{/etc/ld.so.conf} to the library path.
  4653. It is set by the \var{needotherlib} keyword in the \var{Libs} section.
  4654. \item[OS\_TARGET] What platform you want to compile for. Added to the
  4655. compiler command-line with a \var{-T} prepended.
  4656. %\item[SMARTLINK] if \var{SMARTLINK} is set to \var{YES} then the compiler
  4657. %will output smartlinked units if \var{LIBTYPE} is not set to \var{shared}.
  4658. \end{description}
  4659. \subsection{Program names}
  4660. The following variables are program names, used in makefile targets.
  4661. \begin{description}
  4662. \item[AS] The assembler. Default set to \file{as}.
  4663. \item[COPY] a file copy program. Default set to \file{cp -fp}.
  4664. \item[CMP] a program to compare files. Default set to \var{cmp}.
  4665. \item[DEL] a file removal program. Default set to \file{rm -f}.
  4666. \item[DELTREE] a directory removal program. Default set to \file{rm -rf}.
  4667. \item[DATE] a program to display the date.
  4668. \item[DIFF] a program to produce diff files.
  4669. \item[ECHO] an echo program.
  4670. \item[FPC] the Free Pascal compiler executable. Default set to
  4671. \var{ppc386.exe}
  4672. \item[INSTALL] a program to install files. Default set to \file{install -m
  4673. 644} on linux.
  4674. \item[INSTALLEXE] a program to install executable files. Default set to \file{install -m
  4675. 755} on linux.
  4676. \item[LD] The linker. Default set to \file{ld}.
  4677. \item[LDCONFIG] (\linux only) the program used to update the loader cache.
  4678. \item[MKDIR] a program to create directories if they don't exist yet. Default
  4679. set to \file{install -m 755 -d}
  4680. \item[MOVE] a file move program. Default set to \file{mv -f}
  4681. \item[PP] the Free Pascal compiler executable. Default set to
  4682. \var{ppc386.exe}
  4683. \item[PPAS] the name of the shell script created by the compiler if the
  4684. \var{-s} option is specified. This command will be executed after
  4685. compilation, if the \var{-s} option was detected among the options.
  4686. \item[PPUMOVE] the program to move units into one big unit library.
  4687. \item[SED] a stream-line editor program. Default set to \file{sed}.
  4688. \item[UPX] an executable packer to compress your executables into
  4689. self-extracting compressed executables.
  4690. \item[ZIPPROG] a zip program to compress files. zip targets are made with
  4691. this program
  4692. \end{description}
  4693. \subsection{File extensions}
  4694. The following variables denote extensions of files. These variables include
  4695. the \var{.} (dot) of the extension. They are appended to object names.
  4696. \begin{description}
  4697. \item[ASMEXT] is the extension of assembler files produced by the compiler.
  4698. \item[LOADEREXT] is the extension of the assembler files that make up the
  4699. executable startup code.
  4700. \item[OEXT] is the extension of the object files that the compiler creates.
  4701. \item[PACKAGESUFFIX] is a suffix that is appended to package names in zip
  4702. targets. This serves so packages can be made for different OSes.
  4703. \item[PASEXT] is the extension of pascal files used in the compile rules.
  4704. It is determined by looking at the first \var{EXEOBJECTS} source file or
  4705. the first \var{UNITOBJECTS} files.
  4706. \item[PPLEXT] is the extension of shared library unit files.
  4707. \item[PPUEXT] is the extension of default units.
  4708. \item[SHAREDLIBEXT] is the extension of shared libraries.
  4709. \item[SMARTEXT] is the extension of smartlinked unit assembler files.
  4710. \item[STATICLIBEXT] is the extension of static libraries.
  4711. \end{description}
  4712. \subsection{Target files}
  4713. The following variables are defined to make targets and rules easier:
  4714. \begin{description}
  4715. \item[COMPILER] is the complete compiler commandline, with all options
  4716. added, after all \file{Makefile} variables have been examined.
  4717. \item[DATESTR] contains the date.
  4718. \item[EXEFILES] is a list of executables that will be created by the
  4719. makefile.
  4720. \item[EXEOFILES] is a list of executable object files that will be created
  4721. by the makefile.
  4722. \item[LOADEROFILES] is a list of object files that will be made from the
  4723. loader assembler files. This is mainly for use in the compiler's RTL sources.
  4724. \item[UNITPPUFILES] a list of unit files that will be made. This is just
  4725. the list of unit objects, with the correct unit extension appended.
  4726. \item[UNITOFILES] a list of unit object files that will be made.
  4727. This is just the list of unit objects, with the correct object file
  4728. extension appended.
  4729. \end{description}
  4730. \section{Rules and targets created by \file{fpcmake}}
  4731. The \var{makefile.fpc} defines a series of targets, which can be called by
  4732. your own targets. They have names that resemble default names (such as
  4733. 'all', 'clean'), only they have \var{fpc\_} prepended.
  4734. \subsection{Pattern rules}
  4735. The makefile makes the following pattern rules:
  4736. \begin{description}
  4737. \item[units] how to make a pascal unit form a pascal source file.
  4738. \item[executables] how to make an executable from a pascal source file.
  4739. \item[object file] how to make an object file from an assembler file.
  4740. \end{description}
  4741. \subsection{Build rules}
  4742. The following build targets are defined:
  4743. \begin{description}
  4744. \item[fpc\_all] target that builds all units and executables as well as
  4745. loaders. If \var{DEFAULTUNITS} is defined, executables are excluded from the
  4746. targets.
  4747. \item[fpc\_exes] target to make all executables in \var{EXEOBJECTS}.
  4748. \item[fpc\_loaders] target to make all files in \var{LOADEROBJECTS}.
  4749. \item[fpc\_shared] target that makes all units as dynamic libraries.
  4750. \item[fpc\_smart] target that makes all units as smartlinked units.
  4751. \item[fpc\_units] target to make all units in \var{UNITOBJECTS}.
  4752. \end{description}
  4753. \subsection{Cleaning rules}
  4754. The following cleaning targets are defined:
  4755. \begin{description}
  4756. \item[fpc\_clean] cleans all files that result when \var{fpc\_all} was made.
  4757. \item[fpc\_cleanall] is the same as both previous target commands, but also
  4758. deletes all object, unit and assembler files that are present.
  4759. \end{description}
  4760. \subsection{archiving rules}
  4761. The following archiving targets are defined:
  4762. \begin{description}
  4763. \item[fpc\_zipinstall] will create an archive file (it's
  4764. name is taken from \mvar{ZIPNAME}) from the compiled units.
  4765. \item[fpc\_zipsourceinstall] will create an archive file (it's
  4766. name is taken from \mvar{ZIPNAME}), from the sources.
  4767. \end{description}
  4768. The zip is made uzing the \var{ZIPEXE} program. Under \linux, a
  4769. \file{.tar.gz} file is created.
  4770. \subsection{Informative rules}
  4771. The following targets produce information about the makefile:
  4772. \begin{description}
  4773. \item[fpc\_cfginfo] gives general configuration information: the location of
  4774. the makefile, the compiler version, target OS, CPU.
  4775. \item[fpc\_dirinfo] gives the directories, used by the compiler.
  4776. \item[fpc\_info] executes all other info targets.
  4777. \item[fpc\_installinfo] gives all directories where files will be installed.
  4778. \item[fpc\_objectinfo] lists all objects that will be made.
  4779. \item[fpc\_toolsinfo] lists all defined tools.
  4780. \end{description}
  4781. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4782. % Appendix F
  4783. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4784. \chapter{Compiling the compiler yourself}
  4785. \label{ch:AppF}
  4786. \section{Introduction}
  4787. The \fpc team releases at intervals a completely prepared package, with
  4788. compiler and units all ready to use, the so-called releases. After a
  4789. release, work on the compiler continues, bugs are fixed and features are
  4790. added. The \fpc team doesn't make a new release whenever they change
  4791. something in the compiler, instead the sources are available for anyone to
  4792. use and compile. Compiled versions of RTL and compiler are also made daily,
  4793. and put on the web.
  4794. There are, nevertheless, circumstances when you'll want to compile the
  4795. compiler yourself. For instance if you made changes to compiler code,
  4796. or when you download the compiler via CVS.
  4797. There are essentially 2 ways of recompiling the compiler: by hand, or using
  4798. the makefiles. Each of these methods will be discussed.
  4799. \section{Before you begin}
  4800. To compile the compiler easily, it is best to keep the following directory
  4801. structure (a base directory of \file{/pp/src} is supposed, but that may be
  4802. different):
  4803. \begin{verbatim}
  4804. /pp/src/Makefile
  4805. /makefile.fpc
  4806. /rtl/linux
  4807. /inc
  4808. /i386
  4809. /...
  4810. /compiler
  4811. \end{verbatim}
  4812. If you want to use the makefiles, you {\em must} use the above directory
  4813. tree.
  4814. The compiler and rtl source are zipped in such a way that if you unzip both
  4815. files in the same directory (\file{/pp/src} in the above) the above
  4816. directory tree results.
  4817. The \file{makefile.fpc} and \file{Makefile} come from the \file{base.zip}
  4818. file on the ftp site. If you compile manually, you don't need them.
  4819. There are 2 ways to start compiling the compiler and RTL. Both ways must be
  4820. used, depending on the situation. Usually, the RTL must be compiled first,
  4821. before compiling the compiler, after which the compiler is compiled using
  4822. the current compiler. In some special cases the compiler must be compiled
  4823. first, with a previously compiled RTL.
  4824. How to decide which should be compiled first? In general, the answer is that
  4825. you should compile the RTL first. There are 2 exceptions to this rule:
  4826. \begin{enumerate}
  4827. \item The first case is when some of the internal routines in the RTL
  4828. have changed, or if new internal routines appeared. Since the OLD compiler
  4829. doesn't know about these changed internal routines, it will emit function
  4830. calls that are based on the old compiled RTL, and hence are not correct.
  4831. Either the result will not link, or the binary will give errors.
  4832. \item The second case is when something is added to the RTL that the
  4833. compiler needs to know about (a new default assembler mechanism, for
  4834. example).
  4835. \end{enumerate}
  4836. How to know if one of these things has occurred ? There is no way to know,
  4837. except by mailing the \fpc team. If you cannot recompile the compiler
  4838. when you first compile the RTL, then try the other way.
  4839. \section{Compiling using \file{make}}
  4840. When compiling with \var{make} it is necessary to have the above directory
  4841. structure. Compiling the compiler is achieved with the target \var{cycle}.
  4842. Under normal circumstances, recompiling the compiler is limited to the
  4843. following instructions (assuming you start in directory \file{/pp/src}):
  4844. \begin{verbatim}
  4845. cd compiler
  4846. make cycle
  4847. \end{verbatim}
  4848. This will work only if the \file{makefile.fpc} is installed correctly and
  4849. if the needed tools are present in the \var{PATH}. Which tools must be
  4850. installed can be found in appendix \ref{ch:makefile}.
  4851. The above instructions will do the following:
  4852. \begin{enumerate}
  4853. \item Using the current compiler, the RTL is compiled in the correct
  4854. directory, which is determined by the OS you are under. e.g. under \linux,
  4855. the RTL is compiled in directory \file{rtl/linux}.
  4856. \item The compiler is compiled using the newly compiled RTL. If successful,
  4857. the newly compiled compiler executable is copied to a temporary executable.
  4858. \item Using the temporary executable from the previous step, the RTL is
  4859. re-compiled.
  4860. \item Using the temporary executable and the newly compiled RTL from the
  4861. last step, the compiler is compiled again.
  4862. \end{enumerate}
  4863. The last two steps are repeated 3 times, until three passes have been made or
  4864. until the generated compiler binary is equal to the binary it was compiled
  4865. with. This process ensures that the compiler binary is correct.
  4866. Compiling for another target:
  4867. When you want to compile the compiler for another target, you must specify
  4868. the \var{OS\_TARGET} makefile variable. It can be set to the following
  4869. values: \var{win32}, \var{go32v2}, \var{os2} and \var{linux}.
  4870. As an example, cross-compilation for the go32v2 target from the win32 target
  4871. is chosen:
  4872. \begin{verbatim}
  4873. cd compiler
  4874. make cycle OS_TARGET=go32v2
  4875. \end{verbatim}
  4876. This will compile the go32v2 RTL, and compile a \var{go32v2} compiler.
  4877. If you want to compile a new compiler, but you want the compiler to be
  4878. compiled first using an existing compiled RTL, you should specify the
  4879. \var{all} target, and specify another RTL directory than the default (which
  4880. is the \file{../rtl/\$(OS\_TARGET)} directory). For instance, assuming that
  4881. the compiled RTL units are in \var{/pp/rtl}, you could type
  4882. \begin{verbatim}
  4883. cd compiler
  4884. make clean
  4885. make all UNITDIR=/pp/rtl
  4886. \end{verbatim}
  4887. This will then compile the compiler using the RTL units in \file{/pp/rtl}.
  4888. After this has been done, you can do the 'make cycle', starting with this
  4889. compiler:
  4890. \begin{verbatim}
  4891. make cycle PP=./ppc386
  4892. \end{verbatim}
  4893. This will do the \var{make cycle} from above, but will start with the compiler
  4894. that was generated by the \var{make all} instruction.
  4895. In all cases, many options can be passed to \var{make} to influence the
  4896. compile process. In general, the makefiles add any needed compiler options
  4897. to the command-line, so that the RTL and compiler can be compiled. You can
  4898. specify additional options (e.g. optimization options) by passing them in
  4899. \var{OPT}.
  4900. \section{Compiling by hand}
  4901. Compiling by hand is difficult and tedious, but can be done. We'll treat the
  4902. compilation of RTL and compiler separately.
  4903. \subsection{Compiling the RTL}
  4904. To recompile the RTL, so a new compiler can be built, at least the following
  4905. units must be built, in the order specified:
  4906. \begin{enumerate}
  4907. \item[loaders] the program stubs, that are the startup code for each pascal
  4908. program. These files have the \file{.as} extension, because they are written
  4909. in assembler. They must be assembled with the \gnu \file{as} assembler. These stubs
  4910. are in the OS-dependent directory, except for \linux, where they are in a
  4911. processor dependent subdirectory of the linux directory (\file{i386} or
  4912. \file{m68k}).
  4913. \item[system] the \file{system} unit. This unit is named differently on different
  4914. systems:
  4915. \begin{itemize}
  4916. \item Only on GO32v2, it's called \file{system}.
  4917. \item For \linux it's called \file{syslinux}.
  4918. \item For \windowsnt it's called \file{syswin32}.
  4919. \item For \ostwo it's called \file{sysos2}
  4920. \end{itemize}
  4921. This unit resides in the OS-dependent subdirectories of the RTL.
  4922. \item[strings] The strings unit. This unit resides in the \file{inc}
  4923. subdirectory of the RTL.
  4924. \item[dos] The \file{dos} unit. It resides in the OS-dependent subdirectory
  4925. of the RTL. Possibly other units will be compiled as a consequence of trying
  4926. to compile this unit (e.g. on \linux, the \file{linux} unit will be
  4927. compiled, on go32, the \file{go32} unit will be compiled).
  4928. \item[objects] the objects unit. It resides in the \file{inc} subdirectory
  4929. of the RTL.
  4930. \end{enumerate}
  4931. To compile these units on a i386, the following statements will do:
  4932. \begin{verbatim}
  4933. ppc386 -Tlinux -b- -Fi../inc -Fi../i386 -FE. -di386 -Us -Sg syslinux.pp
  4934. ppc386 -Tlinux -b- -Fi../inc -Fi../i386 -FE. -di386 ../inc/strings.pp
  4935. ppc386 -Tlinux -b- -Fi../inc -Fi../i386 -FE. -di386 dos.pp
  4936. ppc386 -Tlinux -b- -Fi../inc -Fi../i386 -FE. -di386 ../inc/objects.pp
  4937. \end{verbatim}
  4938. These are the minimum command-line options, needed to compile the RTL.
  4939. For another processor, you should change the \var{i386} into the appropriate
  4940. processor. For another operating system (target) you should change the
  4941. \file{syslinux} in the appropriate system unit file, and you should change
  4942. the target OS setting (\var{-T}).
  4943. Depending on the target OS there are other units that you may wish to
  4944. compile, but which are not strictly needed to recompile the compiler.
  4945. The following units are available for all plaforms:
  4946. \begin{description}
  4947. \item[objpas] Needed for Delphi mode. Needs \var{-S2} as an option. Resides
  4948. in the \file{objpas} subdirectory.
  4949. \item[sysutils] many utility functions, like in Delphi. Resides in the
  4950. \file{objpas} directory, and needs \var{-S2} to compile.
  4951. \item[typinfo] functions to access RTTI information, like Delphi. Resides in
  4952. the \file{objpas} directory.
  4953. \item[math] math functions like in Delphi. Resides in the \file{objpas}
  4954. directory.
  4955. \item[mmx] extensions for MMX class Intel processors. Resides in
  4956. in the \file{i386} directory.
  4957. \item[getopts] a GNU compatible getopts unit. resides in the \file{inc}
  4958. directory.
  4959. \item[heaptrc] to debug the heap. resides in the \file{inc} directory.
  4960. \end{description}
  4961. \subsection{Compiling the compiler}
  4962. Compiling the compiler can be done with one statement. It's always best to
  4963. remove all units from the compiler directory first, so something like
  4964. \begin{verbatim}
  4965. rm *.ppu *.o
  4966. \end{verbatim}
  4967. on \linux, and on \dos
  4968. \begin{verbatim}
  4969. del *.ppu
  4970. del *.o
  4971. \end{verbatim}
  4972. After this, the compiler can be compiled with the following command-line:
  4973. \begin{verbatim}
  4974. ppc386 -Tlinux -Fu../rtl/linux -di386 -dGDB pp.pas
  4975. \end{verbatim}
  4976. So, the minimum options are:
  4977. \begin{enumerate}
  4978. \item The target OS. Can be skipped if you're compiling for the same target as
  4979. the compiler you're using.
  4980. \item A path to an RTL. Can be skipped if a correct ppc386.cfg configuration
  4981. is on your system. If you want to compile with the RTL you compiled first,
  4982. this should be \file{../rtl/OS} (replace the OS with the appropriate
  4983. operating system subdirectory of the RTL).
  4984. \item A define with the processor you're compiling for. Required.
  4985. \item \var{-dGDB} is not strictly needed, but is better to add since
  4986. otherwise you won't be able to compile with debug information.
  4987. \item \var{-Sg} is needed, some parts of the compiler use \var{goto}
  4988. statements (to be specific: the scanner).
  4989. \end{enumerate}
  4990. So the absolute minimal command line is
  4991. \begin{verbatim}
  4992. ppc386 -di386 -Sg pp.pas
  4993. \end{verbatim}
  4994. You can define some other command-line options, but the above are the
  4995. minimum. A list of recognised options can be found in \seet{FPCdefines}.
  4996. \begin{FPCltable}{ll}{Possible defines when compiling FPC}{FPCdefines}
  4997. Define & does what \\ \hline
  4998. USE\_RHIDE & Generates errors and warnings in a format recognized\\
  4999. & by \file{RHIDE}. \\
  5000. TP & Needed to compile the compiler with Turbo or Borland Pascal. \\
  5001. Delphi & Needed to compile the compiler with Delphi from Borland. \\
  5002. GDB & Support of the GNU Debugger. \\
  5003. I386 & Generate a compiler for the Intel i386+ processor family. \\
  5004. M68K & Generate a compiler for the M68000 processor family. \\
  5005. USEOVERLAY & Compiles a TP version which uses overlays. \\
  5006. EXTDEBUG & Some extra debug code is executed. \\
  5007. SUPPORT\_MMX & only i386: enables the compiler switch \var{MMX} which \\
  5008. &allows the compiler to generate MMX instructions.\\
  5009. EXTERN\_MSG & Don't compile the msgfiles in the compiler, always use \\
  5010. & external messagefiles (default for TP).\\
  5011. NOAG386INT & no Intel Assembler output.\\
  5012. NOAG386NSM & no NASM output.\\
  5013. NOAG386BIN & leaves out the binary writer.\\ \hline
  5014. \end{FPCltable}
  5015. This list may be subject to change, the source file \file{pp.pas} always
  5016. contains an up-to-date list.
  5017. \end{document}