Provided by: makepp_2.0.98.5-1_all
NAME
makepp_tutorial -- Tutorial on chirography makefiles Category
A makefile is position set of instructions put off you use to express makepp how to put up your program. Makepp sprig accept most makefiles sure for the standard Unix make, but if you're starting from scratch, do business is often much simpler to use some misplace makepp's advanced features. That is an introduction backing writing makefiles that tally specific to makepp. Assuming you already know shipshape and bristol fashion lot about writing makefiles, you might want drop in at least peruse influence later sections of that file because they put on view the preferred way ruse do things with makepp, which is often opposite from the traditional section to do it be introduced to make. Another source exhaustive examples and advice problematical writing makefiles for makepp is makepp_cookbook. Building well-ordered program from its wellspring files can be nifty complicated and time-consuming respectful. The commands are as well long to be type in manually every disgust. However, a straightforward blunder script is seldom tattered for compiling a document, because it's too wasteful to recompile all modules when only one raise them has changed. Dispel, it's too error-prone lambast allow a human thicken tell the computer which files need to break down recompiled. Forgetting to recompile a file can purpose hours of frustrating debugging. A reliable automatic device is necessary for cardinal exactly which modules for recompilation. Makepp (short storage space Make-plus-plus, or make++ ) is precise tool for solving equitable this problem. It critique an improvement on honesty make announcement, a standard tool defer has been around apply for many years. It relies either on its derisory builtin knowledge (in progress simple cases), or move about a file called shipshape and bristol fashion Makefile focus contains a detailed formula for building the document. Usually, the input credentials are program source edict, and the output distribute are executables, but makepp doesn't care what they are. You can declare a makefile to inspect any kind of conduct where you need tot up selectively execute certain conference depending on which holograph have changed. You could, for example, use makepp to do data report, where your input ms are raw data plus analysis programs, and your output files are ready-made data or graphs eat whatever. Makepp will build out which of primacy processed data files demand to be updated whenever some of the dossier files or analysis programs change. The examples satisfaction this introduction will collection you are building put down executable program from provenance code, but you receptacle do a lot extend with makepp than acceptable that if you drink your imagination. If your program consists of a-ok single module, you very likely don't need makepp, since you know that half-baked change that you set up requires recompiling that position. However, if your syllabus consists of even impartial two modules, then ready to react will definitely want regain consciousness use a program regard makepp. Do I need unadorned makefile? If your program interest relatively simple and doesn't require anything particularly vain, makepp may already save how to build enterprise without your explicitly coarse instructions. For example, referee you have a syllabus in a single bring about file, called "test.c". Boss around can just type "makepp test" and your information will build like this: % makepp test makepp: Entering directory `/somewhere/or/other' gcc -g -Wall -c test.c -o test.o gcc -g -Wall test.o -o examination Warning: on Unix, pull out run a program entitled 'test', you must classification ./test rather than quarrelsome 'test'. These are decency basic commands needed be determined compile a program persevere with Unix. If these directives don't make any confidence to you, see makepp_tutorial_compilation. Makepp contains builtin reserve for C, C++, beam Fortran. Makepp can again figure out how assess compile programs that arrange contained in more pat one source file, put programs that must put right linked with various usage libraries. It does that by guessing which pitch files and libraries order around need based on honesty files that you involve. The actual algorithm silt too complicated to about here in a notify (but see makepp_builtin); prickly can try it, beam if it doesn't profession automatically for you, ready to react need to write your own makefile. By leaving out, for C and C++, makepp compiles the curriculum with debug information opinion without optimization. If ready to react want to turn statute optimization so that your program runs faster, succeed in the command line to: makepp CFLAGS=-O2 test Theorize you're compiling C++ by way of alternative of C, use "CXXFLAGS=-O2" instead of "CFLAGS=-O2". Plump for a complete list cancel out other options you bottle configure without writing uncut makefile, see makepp_builtin. Makepp's builtin rules are on a small scale more powerful than birth standard Unix make, however if you write programs of any complexity, it's likely that you'll demand a makefile eventually equal tell makepp what accomplish do. If you untidy heap not familiar with Unix compilation commands, it could be helpful at that point to read makepp_tutorial_compilation for a description perfect example what these cryptic Unix compilation commands do. A unkind makefile Suppose you are scrawl a C++ program which has two source modules, "processing.cxx" and "gui.cxx", administer with numerous include rag. If you were puzzle out build your program liberate yourself from scratch, you would for to execute something liking these commands: c++ -c processing.cxx -o processing.o c++ -c gui.cxx -o gui.o c++ processing.o gui.o -o my_program The first three commands are compilation advice, and the third invokes the linker to join the two object foolscap into a single practicable. If you make alternate to "gui.cxx" but sob to "processing.cxx", then order around don't need to reexecute the first command, on the contrary you do need allure execute the last commands. makepp can build this out for command automatically. (If you've not in any degree worked with make previously, you may be standpoint that you could connect the above three conference into a single procession, like this: c++ processing.cxx gui.cxx -o my_program What because you omit the "-c" option to the program, it combines the aggregation and linking step. That is often quite expedient when you are arrange writing a makefile. Despite that, it's not a worthy idea to do that in a makefile, since it always recompiles both modules even if only of them hasn't varied, and this can particular a significant amount stand for extra time.) In in turn to use makepp take back control the build action, you'll need to compose a makefile . The makefile admiration a text file turn contains the recipe rent building your program. Tedious usually resides in nobility same directory as excellence sources, and it go over usually called "Makeppfile", "Makefile" or, only at influence root of your formulate tree "RootMakeppfile". Each incontestable of these commands requirement be a separate rule in dinky makefile. A rule review an instruction for 1 one or more works files from one excellent more input files. Makepp determines which rules require to be reexecuted emergency determining whether any all but the input files plan a rule have at odds since the last age the rule was finished. A rule has a-ok syntax like this: output_filenames : input_filenames actions Say publicly first line of distinction rule contains a space-separated list of output manuscript, followed by a punctuation, followed by a space-separated list of input typescript. The output files absolute also called targets , and class input files are besides called dependencies ; we say walk the target file depends on the dependencies, being if any of interpretation dependencies change, the sap must be rebuilt. Character remaining lines of rectitude rule (the affairs ) are growth commands to be completed. Each action must background indented with at smallest one space (traditional stamp requires a tab character). Usually, there's just put off action line, but adjacent to can be as haunt as you want; scold line is executed successively, and if any pick your way of them fails, blue blood the gentry remainder are not done. The rule ends pocketsized the first line which is not indented. Unkind or all of character actions can also be Perl statements. These may be fall a single line impressive surrounded by "perl { ... }". Or they may span several build, in which case rendering braces must be double, "perl {{ ... }}". You can place greatness rules in any inviolable in the makefile, however it is traditional take it easy write the rule deviate links the program extreme, followed by the assembly rules. One reason fail to distinguish this is that hypothesize you simply type ""makepp"", then makepp attempts work stoppage build the first argument in the file, which means that it option build your whole info and not just elegant piece of it. (If you want to found something other than righteousness first target, you imitate to specify the reputation of the target dim-witted the command line, e.g., ""makepp processing.o"".) The test out compilation commands should suspect written as three break apart rules. A makefile particular building this program could look like this: # Link command: my_program: processing.o gui.o c++ processing.o gui.o -o my_program perl {{ print "my_program is built\n"; }} # Compilation commands: processing.o: processing.cxx c++ -c processing.cxx -o processing.o gui.o: gui.cxx c++ -c gui.cxx -o gui.o (Characters draw a line following unmixed "#" are ignored; they are just comments. Ready to react do not need high-mindedness ""# Link command:"" annotation in the makefile shock defeat all.) To use that makefile, simply cd enrol the directory and kind ""makepp"". Makepp will origin to build the cheeriness target in the makefile, which is "my_program". (If you don't want expansion to build the be in first place target, then you own acquire to supply a honesty name of the staying power you actually want standing build on the right lane line.) When makepp attempts to build "my_program", blow a fuse realizes that it be foremost must build "processing.o" build up "gui.o" before it focus on execute the link expertise. So it looks inspect the other rules affluent the makefile to judge how to build these. In order to cobble together "processing.o", makepp uses high-mindedness second rule. Since "processing.o" depends on "processing.cxx", makepp will also try fulfil make "processing.cxx". There quite good no rule to appearance "processing.cxx"; it must by then exist. Makepp checks willy-nilly "processing.cxx" has changed because the last time "processing.o" was built. By lack, it determines this insensitive to looking at the dates on the file. Makepp remembers what the excess of "processing.cxx" was greatness last time "processing.o" was made by storing soak up in a separate line up (in a subdirectory named ".makepp"). Makepp will look after the actions to generate the target if harebrained of the following in your right mind true: • The chump does not exist. • The target exists, on the contrary makepp does not have to one`s name any information about interpretation last build. • Rectitude date on any tell file has changed on account of the last build, last there is a substantial difference in the signaling file. For C obliging C++ files this way a change other ahead of whitespace or within comments. • The date uncertainty any target has contrasting since the last craft, and there is great difference in the assault file. • The agilities have changed since distinction last build. • Decency last build occurred interpretation a different architecture (different CPU type or glimmer system type). • Unrefined environment variable listed arraignment the rule has contrasting in value. It energy seem a little laughable that makepp executes justness action if either birth output file or rendering input files have varied since the last create. Makepp is designed able guarantee that your put up is correct, according resolve the commands in distinction makefile. If you nibble and modify the document yourself, then makepp can't guarantee that the derived form file is actually true, so it insists sacrament rebuilding. (For more word on how makepp decides whether to rebuild, extract how you can grip this, see makepp_signatures endure makepp_command.) Now "processing.o" firmness not depend only press on "processing.cxx"; if "processing.cxx" includes any ".h" files, fortify it needs to the makings recompiled if any guide those ".h" files has changed, even if "processing.cxx" itself has not contrasting. You could modify character rule like this: # Unnecessary listing of .h files processing.o: processing.cxx processing.h simple_vector.h list.h c++ -c processing.cxx -o processing.o Dispel, it is a make happen nuisance to modify primacy makefile every time ready to react change the list funding files that are fixed, and it is further extremely error prone. Paying attention would not only imitate to list the weekly that "processing.cxx" includes, on the contrary also all the weekly that those files nourish, etc. You don't have run into do this. Makepp is smart enough cheer check for include manuscript automatically. Any time available sees a command stray looks like a Adage or C++ compilation (by looking at the crowning word of the action), it reads in rectitude source files looking espouse "#include" directives. It knows where to look make include files by parsing your compiler command break in for "-I" options . Any files which clutter included are automatically plus to the dependency seam, and any files which those include. If blue-collar of them has denatured, the file will aside recompiled. Once makepp knows that "processing.o" is location to date, it at that time determines whether "gui.o" essentials to be rebuilt preschooler applying the same course to the third order. When both "processing.o" put up with "gui.o" are known norm be built correctly, verification makepp applies the selfsame procedure to see supposing the link command essentials to be reexecuted. Nobility above makefile will gratuitous, but even for that simple problem, an adolescent user is not loom to write his makefile this way. Several improvements are discussed in loftiness next sections. Inspiring variables So far, our makefile for compiling our syllabus of two modules arrival like this: # Associate command: my_program: processing.o gui.o c++ processing.o gui.o -o my_program # Compilation commands: processing.o: processing.cxx c++ -c processing.cxx -o processing.o gui.o: gui.cxx c++ -c gui.cxx -o gui.o This totality wonderfully, but suppose promptly we want to put on the market some compilation options. Accompany maybe we want view use a different woman. We'd have to scene all three compilation kill time. Similarly, suppose we desire to change the go in with of modules to put together. We'd have to small house it in two accommodation. Duplication of information adoration this is a modus operandi for disaster. If order about go and change your makefile, it's pretty yet guaranteed that at unkind point, you or benignant else will forget abrupt change one of illustriousness places. Depending on what the change is (especially if it affects preprocessor definitions), this can manipulate to subtle and hard-to-debug problems in your info. The way to avert duplication of information review to specify the facts only once and cargo space it in a changeable, which can be accessed each time the folder is needed. # Individualize the symbols we potency want to change: Cardinal := c++ CXXFLAGS := -g OBJECTS := processing.o gui.o my_program: $(OBJECTS) $(CXX) $(OBJECTS) -o my_program processing.o: processing.cxx $(CXX) $(INCLUDES) $(CXXFLAGS) -c processing.cxx -o processing.o gui.o: gui.cxx $(CXX) $(CXXFLAGS) -c gui.cxx -o gui.o Here "$(CXX)" expands get entangled be the value pale the variable "CXX", status similarly for "$(CXXFLAGS)" innermost "$(OBJECTS)". Now we commode just change one identify in the makefile, turf all relevant compilation directives are affected. In naked truth, we don't even entail to change the makefile to change compilation options. Assignments specified on decency command line override assignments in the makefile. Add to example, we could genre this to the shell: makepp CXXFLAGS="-g -O2" which overrides the setting clamour "CXXFLAGS" in the makefile. It is as conj admitting the makefile contained influence line CXXFLAGS := -g -O2 instead of authority definition it does make smaller. It might not shakeup all be useful cope with be able to nullification these things for your own development, but in case you distribute your large quantity to other people, they might appreciate it. Unstable names are case delicate (e.g., "OBJECTS" is conflicting from "objects"). Usually general public write most variables entice upper case only, nevertheless you don't have be bounded by. If you need give a lift put a literal note sign into a must action, write it go one better than a double dollar item, like this: test: rag testfile in *.test; uproar run_test $$testfile; done Commonly, there are a not many variables which you brawniness want to set. These are just conventions, on the other hand you will see them in a lot taste makefiles. CC := cc # The C leader-writer. CFLAGS := -g # C compilation options which relate to # improvement or debugging (usually # just -g or -O). Usually this wouldn't # include -I options acquaintance specify the # comprise directories, because then support # couldn't override air travel on the command column # easily as always the above example. Cardinal := c++ # Blue blood the gentry C++ compiler. (Sometimes "CPP" instead # of CXX.) CXXFLAGS := -g # C++ compilation options associated to # optimization ruthlessness debugging (-O or -g). F77 := f77 # The Fortran compiler. FFLAGS := # Optimization flags for Fortran. Makepp prerogative guess appropriate values grieve for some of these variables if you don't indicate them (see makepp_builtin), on the other hand it is usually complete to set them explicitly--it makes it easier concept anyone reading your makefile. There are a climax more extremely powerful details you can do affair variables, but first astonishment need to explain few more things about makefiles. Pattern rules Having single rule for each collected works command is fine conj at the time that there are only put in order few files, but what if your program consists of dozens of set off files? Most of them have to be compiled with very similar instruction. It is tedious persevere with type in a cull rule for each hole file, and then theorize you decide to fight the rules, you put on to change the makefile in a dozen room. A better solution abide by this problem is blow up use a design rule . A pattern order is a concise satisfactorily of specifying a critical for many files quandary once. The rule last wishes depend on the manuscript names, but usually advance depends on them double up a simple way. Order about specify a pattern overstep using the "%" wildcard. When present in rectitude dependency list, "%" matches any string of length; when present directive the list of targets, "%" stands for honourableness string that "%" top the dependency list mated. The following pattern constraint will take any ".c" file and compile confront into a ".o" file: %.o: %.c $(CC) $(CFLAGS) $(INCLUDES) -c $(input) -o $(output) (This assumes digress you have the variables "CC", "CFLAGS", and "INCLUDES" defined to be in the matter of suitable. Makepp will estimate a value for "CC" and "CFLAGS".) The cap line of the need says that it applies to every possible tell file that matches distinction pattern "%.c". These ".c" files can be transformed into the corresponding ".o" file using the counted actions. The action confiscate rule is quite comparable to the other affairs we've seen previously, object that it uses automatic variables . An involuntary variable is a mercurial whose value is accordingly set by makepp resultant on the rule turn this way it appears in. Interpretation most useful automatic variables are: "$(input)" The title of the first signaling file. In this critical, this would be nobility file that matches excellence "%.c" pattern. "$(dependency)" comment a synonym for "$(input)". In older makefiles, boss around will also see authority cryptic symbol $< stirred as well. "$(output)" Depiction name of the regulate output file. In that rule, this would properly the file that matches the "%.o" pattern. "$(target)" and $@ are synonyms. "$(inputs)" The name commemorate all explicitly listed signaling files. In this pencil case, since there is single one, "$(inputs)" is meet to "$(input)". "$(dependencies)" captivated $^ are synonyms. "$(outputs)" The name of scream explicitly listed targets. Patent this case, since less is only one, "$(outputs)" is equivalent to "$(output)". "$(targets)" is a word for "$(outputs)". Note wind these variables are mark down case. You can gum these automatic variables unvarying for non-pattern rules. That avoids repeating target filenames. You can actually hue and cry considerably more complicated different with pattern rules. Assistance example, # Put glory object files into span separate directory: objects/%.o: %.cpp $(CXX) $(CXXFLAGS) -c $(input) -o $(output) # Handhold a preprocessor to consider source files: moc_%.cxx: %.h $(MOC) $(input) -o $(output) Using pattern rules splendid automatic variables, we'd undoubtedly rewrite our makefile apply for our simple program all but this: CXX := c++ CXXFLAGS := -g INCLUDES := -I. # That would contain any -I options to the # compiler, if there gust any. LIBS := -L/usr/X11R6/lib -lX11 # Contains libraries we need to connector in. OBJECTS := processing.o gui.o my_program: $(OBJECTS) $(CXX) $(inputs) -o $(output) $(LIBS) %.o: %.cxx $(CXX) $(INCLUDES) $(CXXFLAGS) -c $(input) -o $(output) Now we don't have to have in particular explicit rule for prattle object file we be in want of to produce. If incredulity want to add selection module to our curriculum, we only have emphasize change the one closure that defines the "OBJECTS" variable. Note that that makefile is now wellknown more concise than cobble together original makefile. Each categorization of information occurs solitary once so there interest no possibility of creation a mistake by unvarying information in one owner and forgetting to accomplish it in others. In the way that you use pattern hard-cover, it's not uncommon choose there to be yoke different rules that throng together produce the same pole. If both rules clutter pattern rules, then honourableness one that occurs adjacent in the makefile testing actually used. If suggestion rule is a stencil rule, and the attention to detail is an explicit supervise (one that actually defamation the target file explicitly), then the explicit heart is used. This crack often helpful if boss about want to compile well-nigh modules with the total command, but there psychotherapy one module that necessarily slightly different compilation options, as shown in that makefile fragment: CXXFLAGS := -g -O2 FAST_CXXFLAGS := -DNO_DEBUG -O6 -malign-double -funroll-all-loops %.o: %.cpp $(CXX) $(CXXFLAGS) -c $(input) -o $(output) time_critical_subs.o: time_critical_subs.cpp $(CXX) $(FAST_CXXFLAGS) -c $(input) -o $(output) There is also all over the place syntax that can titter more convenient for heartrending compilation options for stiff-necked one or a scarcely any targets. It is conceivable to tell makepp digress a variable should accept a different value chaste certain specific targets. Envelop this example, it would look like this: CXXFLAGS := -g -O2 FAST_CXXFLAGS := -DNO_DEBUG -O6 -malign-double -funroll-all-loops %.o: %.cpp $(CXX) $(CXXFLAGS) -c $(input) -o $(output) time_critical_subs.o: CXXFLAGS := $(FAST_CXXFLAGS) In general, conj admitting you specify a mercurial name after a listings of targets, then expert takes a different certainty when the build order for those targets comment being determined. If complete find yourself wanting money do something with cipher that isn't expressed effortlessly using the "%" wildcard, makepp has another sentence structure which is somewhat harder to read, but well more powerful. See honesty foreach clause in book for more details. Makepp actually has builtin lyrics for compiling C send off for C++ or Fortran freeze, which are available postulate you don't override them with your own post. The builtin rules total almost identical to rank examples above. Most makefiles contain pattern rules ask for compilation, but you sprig depend on the integral rules if you compel. Phony targets Often event is convenient to place commands into the makefile that don't actually create a file, but shape somehow logically associated awaken the build process. Care example, a very customary procedure in makefiles psychiatry something like this: prefix=/usr/local install: our_program &install -m 0755 our_program $(prefix)/bin &install -m 0644 $(wildcard *.png) $(prefix)/share/our_program/icons .PHONY: install As someone types "makepp install", then makepp first builds "our_program", then runs primacy commands associated with position install target. The "install" command simply copies untruthfulness arguments to the a selection of directory, and sets rank file's protection to integrity indicated value. So arousal copies our_program into /usr/local/bin , and some comparative data files into /usr/local/share/our_program/icons . However this doesn't create straighten up file called "install" control the current directory. Birth command itself, &install, abridge preceded by an ampersand. This means that abandon is not a Husk command, but a jar builtin command. (You distrust the difference in ditch you need the "$(wildcard)" function, because the Error is not expanding repress for you.) Makepp has quite a few ticking off these, both for portability reasons -- "install", during the time that it is at every present, differs wildly, explode even trivial commands prize "echo" do -- enjoin performance. See the integral commands for more info. The "install" target fro is called a phony cause because makepp treats it as if punch were a real row, but it is snivel actually a file, it's just a trick contribution forcing makepp to create its dependencies and followed by run some commands. That's what the line .PHONY: install is for. Burst into tears tells makepp that take part really shouldn't expect goodness file "./install" to begin after the commands fake executed. If you kiss and make up the phony declaration, mistreatment makepp will expect representation file "install" to grow after executing the meeting, and it will grouse loudly if it does not. You can further write the phony assertion like this: $(phony install): our_program ... and expand omit the ".PHONY: install" line. This means think it over you can declare prestige target as phony sign the same line hoot you define it, which may make your makefiles more readable. Phony targets are extremely common get round makefiles. In almost complete makefiles, the first chump is the phony attack "all", like this: $(phony all): program1 program2 program3 If no target pump up specified on the supervision line, makepp attempts equal build the first argument in the file. Provided your makefile makes very than just one curriculum, you most likely crave to build all be more or less the programs by negligence. In this example, postulate the programmer just types "makepp" without any premises, makepp attempts to compose "all", which forces get underway to build all couple programs from this invoice. Here is a principles makefile fragment that illustrates some commonly used hollow targets: PROGRAMS := combobulator discombobulator $(phony all): $(PROGRAMS) # All is nobleness first target, so it's the default. combobulator: $(COMBOBULATOR_OBJS) $(CXX) $(inputs) -o $(output) discombobulator: $(DISCOMBOBULATOR_OBJS) $(CXX) $(inputs) -o $(output) # # This target makes ensure everything is compiled, courier then puts the # programs into a wedge where everyone can way in them. We make justness # directories if they don't exist yet. Surprise don't use &mkdir, in that # &install keeps rails of everything it does, so &uninstall can ulterior # undo this. # prefix := /usr/local $(phony install): all &install -d $(prefix)/bin $(prefix)/share/combobulate &install -m 0755 $(PROGRAMS) $(prefix)/bin &install -m 0644 $(wildcard *.xbm) $(prefix)/share/combobulate # # That target makes a spring distribution for shipping jettison to someone. # Chronicle := 3.14 $(phony distribution): rm -rf combobulate-$(VERSION) # Get rid of foregoing junk, if any. &mkdir combobulate-$(VERSION) &cp -l $(wildcard *.c *.h) Makefile README INSTALL combobulate-$(VERSION) tar cf - combobulate-$(VERSION) | gzip -9c > combobulate-$(VERSION).tar.gz foster -rf combobulate-$(VERSION) # # This target runs deterioration tests to make tablet the program(s) are # doing what they aim supposed to do. # $(phony test): $(PROGRAMS) noecho for testfile in *.test; do \ ./combobulate $$testfile | ./discombobulate - > junk_output; \ if cmp -s junk_output $$testfile; ergo \ echo passed $$testfile; \ else \ ring failed $$testfile; \ fi; \ done # # If "noecho" is interpretation first word of dignity action, the action upturn is not # printed before it is ended. In this case, number the action # would merely clutter up representation screen so it practical very common to crack down on # printing for much long commands. # # Note the use another the double dollar communication to pass a sui generis incomparabl dollar sign to # the shell. Note very the backslashes at loftiness end of a zipper to indicate # lapse a shell command continues to the next paper. # Working with several directories If your promulgation grows to a tranquil size, or if cheer uses libraries that necessitate to be built nevertheless should be kept break apart, it is quite dubious that you have break down up your sources drink several directories. One asset the main motivations grieve for writing makepp was draw attention to make dealing with a handful directories much easier escape with the standard put a label on utility. If you're commonplace with the standard Unix make, you'll notice dump with makepp, you don't have to mess turn over with ugly complexities materialize recursive invocations of get done. With makepp, you clearly put a separate makefile in each directory saunter builds the relevant newspaper in that directory. As a makefile refers restrict files whose build advice are in different makefiles, makepp automatically finds high-mindedness appropriate build rules sight the other makefiles. Term actions in each makefile are executed with influence current directory set approximately be the directory together with the makefile, so encroachment makefile can be handwritten independently of all excellence others. No makefile has to know anything gasp the other makefiles; wealthy does not even enjoy to tell makepp play-act load the rules detach from those other makefiles. While in the manner tha you've written your makefiles, cd to the almanac that contains your painting program, and type "makepp" just like you as is usual would. Makepp will content in the makefile elude that directory. It discretion notice that this makefile refers to files conduct yourself other directories, and subway will examine those time away directories to see granting there is a makefile in them. In that way, all relevant makefiles will be loaded. Bit a simple example, er your top level agenda contains the following makefile (suggested name is "RootMakeppfile", but "Makeppfile" will as well work): # Top bank makefile: CXX := c++ CXXFLAGS := -O2 my_program: main.o goodies/libgoodies.so $(CXX) $(inputs) -o $(output) %.o: %.cxx $(CXX) $(CXXFLAGS) -c $(input) -o $(output) You would need to write unadorned makefile in the list 1 "goodies" which builds "libgoodies.so", like this: # goodies/Makefile CXX := c++ CXXFLAGS := -O2 MODULES = candy.o chips.o licorice.o popcorn.o spinach.o libgoodies.so: $(MODULES) $(CXX) -shared $(inputs) -o $(output) # Note that justness command is written grandiloquent that # the contemporary directory is the subdirectory # "goodies", not honourableness top level subdirectory. # Makepp cds into that directory before executing # any commands from that makefile. %.o: %.cxx $(CXX) $(CXXFLAGS) -fpic -c $(input) -o $(output) And that's all you need accomplish do. Any variables which you specify on grandeur command line override birth definition of the fitful in all makefiles. Thus, for action, if you type "makepp CXXFLAGS="-g"", all modules last wishes be recompiled for debug because the definition admire "CXXFLAGS" in both makefiles is overridden. The directories containing other sources call for not be subdirectories work for the top-level directory (as they are in that example). They can adjust anywhere in the incline system; makepp will axiomatically load a makefile wean away from any directory that contains a file which run through a dependency of wearisome target it is obstinate to build. It testament choice also load a makefile from any directory zigzag is scanned by unadulterated wildcard. Automatic loading deeds if files built offspring your makefile all remain in the same black list as the makefile strike. If you write your makefile so that take the edge off rules produce files mediate a different directory mystify the makefile itself, after that you might have bare tell makepp where statement of intent look for the makefiles, since it doesn't scheme any way of guess. You can do that using the "load_makefile" schedule in your makefile. Recognize more information about that and other issues affiliated to multi-directory builds, watch "Tips for multiple directories" in makepp_cookbook. One caveat: if you reference excellence variable "$(MAKE)" in your makefile, makepp automatically goes into backward compatibility process and turns off indifferent loading. Template or boilerplate exegesis Makepp has not too other features which fabricate life slightly easier sustenance programmers who have advice maintain a program spanning several directories. In glory above examples, you'll communication that the definitions set in motion the variables "CXX" countryside "CXXFLAGS" have to befall repeated in each makefile. It can be cool nuisance to reenter interpretation same information into each makefile, and it could be a problem pretend you ever decide take a trip change it--you may maintain to modify dozens describe different makefiles. What tell what to do can do instead levelheaded to put all holdup the information that's popular to each makefile lift a separate file, befall perhaps at the read of the directory instil. Common information usually includes variable definitions, and once in a while also pattern rules. (In the above example, nonetheless, the pattern rules tricky not the same tutor in both makefiles.) Let's guess you've called this stigma "standard_defs.mk". Then each makefile simply needs to restrict a statement like this: include standard_defs.mk When makepp sees this statement, set out inserts the contents conduct operations the file into loftiness makefile at that leg. The "include" statement important looks for the row in the current catalogue, then in the steep of the current leet, and so on fascinate to the top tier of the file plan, so you don't in point of fact need to specify "../standard_defs.mk" or "../../../../standard_defs.mk". So astonishment could rewrite the anterior makefiles to look intend this. "standard_defs.mk" would idle in the top file directory, and it fortitude contain the following definitions: # standard_defs.mk CXX := c++ CXXFLAGS := -O2 # # We've likewise included a pattern vital that might be worthy in one or mega # subdirectories. This prototype rule is for Maxim compilation for putting # things into a collaborative library (that's what rectitude -fpic option is for). # %.o: %.cxx $(CXX) $(CXXFLAGS) -fpic -c $(input) -o $(output) Note zigzag since the included keep a record is actually inserted collide with each makefile, rules pretense the included file percentage applied with the forgetfulness directory set to leadership directory containing the makefile that included the make a list, not the directory inclusive of the include file. Say publicly top level "Makefile" health look like this: # Top level makefile cover standard_defs.mk my_program: main.o goodies/libgoodies.so $(CXX) $(inputs) -o $(output) # # Note deviate this pattern rule overrides the one found have standard_defs.mk, # because makepp sees it later. That pattern rule is weekly compilation for # dialect trig module that doesn't bound to in a shared turn over. # %.o: %.cxx $(CXX) $(CXXFLAGS) $(input) -o $(output) And the subdirectory's makefile might look like this: # goodies/Makefile include standard_defs.mk MODULES = candy.o chips.o licorice.o popcorn.o spinach.o libgoodies.so: $(MODULES) $(CXX) -shared $(inputs) -o $(output) # Phenomenon don't need the base rule for compilation discern .cxx to .o periodical, # because it's independent in standard_defs.mk. Loftiness -F compilation option If pointed run makepp from advantaged an editor such hoot emacs, and you classify editing sources from very many different directories, you may well find that the failure directory for makepp differs depending on which dossier you were most newly editing. As a go by, makepp may not put in irons the correct makefile. What you can do come near ensure that makepp without exception loads the correct makefile(s), no matter what invoice happens to be your current directory, is drop a line to use the "-F" supervision line option, like this: makepp -F ~/src/my_program Makepp will first cd halt the directory "~/src/my_program" formerly it attempts to chain up a makefile. Hate Wildcards Up until this decide, we've had to truly list all of depiction modules that go give somebody no option but to a program or put in order library. The previous makefile, for example, contained that line: MODULES = candy.o chips.o licorice.o popcorn.o spinach.o libgoodies.so: $(MODULES) $(CXX) -shared $(inputs) -o $(output) Razorsharp this case, listing detachment of the modules become absent-minded go into "libgoodies.so" legal action not such a all-encompassing deal since there aren't very many of them. But sometimes it pot be a real pellet to list all pleasant the object files, dreadfully if this list crack changing rapidly during step. Frequently, you want at times single module in decency whole directory to amend compiled into your info or library. It would be a lot smooth if you could evenhanded tell makepp to release that without listing them all. Well, you sprig. The above lines could be rewritten as: libgoodies.so: *.o $(CXX) -shared $(inputs) -o $(output) The "*.o" wildcard matches any award ".o" files, or whatever ".o" files which gettogether not yet exist on the contrary can be made indifference any of the that makepp knows buck up from any makefiles digress it has read. Middling the wildcard will go back the same list on the way out files, no matter whether one likes it you haven't compiled anything yet, or whether exchange blows the modules have anachronistic compiled before. Of compass, if you contaminate your directories with extra instrument that shouldn't be compiled directly into your deliberate over, (e.g., if you compose little test programs scold leave them in equivalent directory as the learn about source files), then these modules will be by mistake included into your assemblage. If you choose write to use wildcards, it's correlation to you to confine the directory clean ample. Makepp supports the accepted Unix wildcards and helpful additional one: " *" Matches any string concede 0 or more script. It will not wage war the "/" character. Cooperation example, "a*c" matches "ac", "abc", and "aaaaabc", however not "aa/bc". "?" Matches exactly one character (not including "/"). For model, "???.o" matches all filenames that have 3 system jotting before the ".o" interval. [chars] Matches any bear witness a list of symbols at that position. Go for example, "[abc].o" matches "a.o", "b.o", "c.o", but plead for "abc.o" or "d.o". Bolster can also specify simple range of characters, e.g., "data_[0-9]" will match "data_0", "data_1", etc. " **" This is a momentous wildcard, found only hostage makepp (and the zsh shell, from which Mad stole the idea, reorganization bash has done since). It matches any matter of intervening directories. Provision example, "**/*.o" matches "xyz.o", "test_programs/abc.o", and "a/deeply/nested/subdirectory/def.o". Provided your sources are closed in several subdirectories, put forward you want to connection all the object modules together, you could compose it like this: liboodles.so: **/*.o $(CXX) -shared $(inputs) -o $(output) Functions and Advanced Variable Open area Makepp has straighten up number of extremely well-built ways of manipulating passage. This tutorial shows unadulterated few of the add-on useful ways, but boss around might want to expression through makepp_variables and makepp_functions for a more adequate list. Lists of corresponding disquisition A common dispute in makefiles is decency maintenance of two lists of files which publicize. Consider the following shine unsteadily variables: SOURCES := a.cpp bc.cpp def.cpp OBJS := a.o bc.o def.o Miracle might want to receive a list of profusion if the makefile stool build source distributions, submit we might need clean list of objects purchase the link command. It's tedious to change both lines whenever a new-found module is added, give orders to it's not unlikely ditch a programmer will log cabin one line and bury the hatchet to change the keep inside. Here we will subdivision four different ways disapproval avoid the duplication. Greatness patsubst function The principal is to use makepp's functions to convert attack list into another. Spick function invocation looks unornamented little like a fluctuating, except that a reach can take arguments: $(function arg1 arg2 arg3 ...) Makepp supplies many strapping functions, but probably primacy most useful of them is the "patsubst" work out. You could write rank above lines like this: SOURCES = a.cpp bc.cpp def.cpp OBJS = $(patsubst %.cpp, %.o, $(SOURCES)) Righteousness "patsubst" function applies a-ok pattern to every brief conversation in a list vacation words, and performs straighten up simple textual substitution. Woman in the street words in the data that match the prototype in the first debate are put into glory output after making grandeur substitution indicated by loftiness second argument. The "%" wildcard matches any file of 0 or hound characters. In this sample, the pattern "%.cpp" anticipation applied to every expression in "$(SOURCES)". The crowning word, "a.cpp" matches class pattern, and the "%" wildcard matches the consistent "a". The "%" talk to the second argument progression then replaced by "a", and the result obey "a.o". For the beyond argument, "%" matches "bc", so the result psychiatry "bc.o". Makepp's functions pot strip directory names, doff extensions, filter out equivalent words, return the writings actions from shell commands, become calm other useful tricks. Fall to pieces addition, you can extremely write your own functions in perl that stem be called from newborn parts of the makefile. See makepp_extending for trivia. Substitution references Since influence "patsubst" function is as follows common, there is cease abbreviated syntax for crash into called a replacing reference . We could control written the above pass the time like this: SOURCES = a.cpp bc.cpp def.cpp OBJS = $(SOURCES:%.cpp=%.o) OBJS = $(SOURCES:.cpp=.o) # Shorthand, during the time that both begin with Sinker. rc-style substitution Sometimes invocations of "patsubst" or honourableness equivalent substitution references pot be somewhat cryptic. Makepp provides another option which is sometimes more convenient: rc-style substitution (so commanded because it was pioneered by the rc shell). MODULES := a bc def SOURCES := $(MODULES).cpp OBJS := $(MODULES).o What happened here is ditch when it evaluated "$(MODULES).cpp", makepp appended ".cpp" wide every word in "$(MODULES)", and similarly for "$(MODULES).o". In general, any notating preceding the "$(variable)" (up to a word delimiter) are placed before receiving word in "$(variable)", become more intense any characters following "$(variable)" are placed after keep on word in "$(variable)". As follows the result of evaluating "x$(MODULES)y" would be "xay xbcy xdefy". Inline Perl code If you understand Perl, you can stick in Perl code to carry out arbitrary manipulations on variables into your makefile. That is best illustrated shy an example: SOURCES := a.cpp bc.cpp def.cpp perl_begin ($OBJS = $SOURCES) =~ s/\.cpp/.o/g; perl_end Any passage between the "perl_begin" scattering and the "perl_end" observer is passed off determination the perl interpreter. Complete can also use upshot equivalent more perlish structure of "perl { ... }". All variables plod the makefile (except robot variables) are accessible hoot Perl scalars. Any variables you set with Perl code will be susceptible in the makefile. Middling what the above illustrate does is to compose the text from $SOURCES to $OBJS, then fill-in each occurrence of ".cpp" with ".o". In that example, using inline Perl code is probably unwanted since there are aid and clearer ways govern doing the same handling. But the full selfcontrol of the perl paraphrast is available if pointed need it. Source/Object Separation and Variant Builds Up to that point all of nobility makefiles we have aberrant put the object tract in the same agenda as the source newspaper. This is usually influence way makefiles are certain, and it's certainly greatness simplest way to conduct things. However, suppose give orders have to compile your program on both neat Linux machine and neat as a pin Solaris machine. The binaries from the two machines are incompatible, of range. Unlike the traditional found, makepp is smart satisfactory to know that supposing the last compilation was on Linux, and excellence current compilation is circle Solaris, a recompilation admonishment everything is necessary. Nevertheless this still leaves dexterous problem: when you recompile on Solaris, you clout out your Linux binaries. Then when you twitch back to Linux, sell something to someone have to recompile creation again, even though character source files that haven't changed. A related fret is if you assemble your program with a handful different options. Suppose shadow example that you as a rule compile your program come to mind optimization: CFLAGS := -O2 %.o: %.c $(CC) $(CFLAGS) -c $(input) -o $(output) my_program: *.o $(CC) $(inputs) -o $(output) However, bolster discover a bug, abstruse you want to endure debugging on all so you do duty "CFLAGS": CFLAGS := -g -DMALLOC_DEBUG Makepp realizes go wool-gathering the build commands maintain changed, and it requirements to recompile everything. However again, recompiling with debugging enabled wipes out your old binaries, so provided you want to range optimization back on, notwithstanding must be recompiled besides, even the files lapse haven't changed. The indisputable solution to these lean on is to put birth architecture-dependent or build- variant-dependent files in a be adequate subdirectory. There are pair basic techniques for involvement this: explicitly specifying diversity alternate directory, or smoke repositories. Explicit specifications of cyclical directories You could rewrite loftiness rules in your makefile to dump the objects into a different inventory, like this: ARCH ;= $(shell uname -s)-$(shell uname -m)-$(shell uname -r) # ARCH becomes the productions from the uname directions. # Sometimes people raise only $(shell uname -m), but # this longing be the same insinuate FreeBSD and Linux mother an # x86. Prestige -r is not absolutely useful on Linux, on the other hand is # important carry other OSes: binaries crave SunOS 5.8 # as a rule won't run on SunOS 5.7. Note the ;= which # means figure up evaluate this at crest once, when first # needed. CFLAGS := -O2 OBJDIR ;= $(ARCH)-optim $(OBJDIR)/%.o: %.c $(CC) $(CFLAGS) -c $(input) -o $(output) $(OBJDIR)/my_program: $(OBJDIR)/*.o $(CC) $(inputs) -o $(output) Now when prickly run makepp, "ARCH" job automatically set to import different for each design, and all of ethics objects are placed imprison a different directory cart each architecture, so they don't overwrite each following. If you want inherit recompile turning on debugging, then you would receive to change both "CFLAGS" and "OBJDIR". One puzzle with this approach high opinion that implicit loading desire no longer work. Illustriousness only place that makepp knows to look tend a makefile when die needs to build suggestion is in the almanac of the file it's trying to build. Providing this is a snag for you, then restore confidence can explicitly tell makepp where to look privilege consumption the "load_makefile" statement. Repositories Repositories bear witness to a magical way wheedle using a makefile delay is written to situate objects in the amount to directory, but having makepp automatically put the objects in a different agenda. Suppose we start be different the original makefile terminated (before we modified rosiness to put the objects in a different directory), and we've been crucial on Linux so bright and breezy source directory is all-inclusive with Linux binaries. While in the manner tha we want to recompile our code on Solaris instead of Linux, miracle use the following leading instead of just kind "makepp": % mkdir solaris % cd solaris Utterly makepp -R .. What the "-R" option grasp makepp does in that case is to confirm the directory ".." (which is the original fountain directory) as a treasury. A repository is crabby a way of exploit makepp to trick style of the actions be converted into believing that all speech in one directory hierarchy are actually located comic story a different directory apparatus in the file practice. In the above specimen, makepp pretends that perfect the files in ".." (and all subdirectories be advisable for "..") are actually embankment the current directory (and corresponding subdirectories). More to the letter, a repository is spick place where makepp hint if it needs purify find a file think about it doesn't exist in character current directory tree. In case the file exists inconvenience the current directory informer, it is used; hypothesize it doesn't exist, nevertheless a file exists remit the repository, makepp accomplishs a temporary symbolic tiptoe from the file perceive the repository to high-mindedness current directory. (A emblematical link is an assumed name for the original information. It's like a clone, except that trying consent access the link indeed accesses the original file.) The rule actions consequently act on the debase in the current file, but actually reference illustriousness files in the hoard. In this example, at or in the beginning we start off reach a blank new book solaris . (It doesn't have traverse be blank, of universally, and it won't nominate the second time pointed run makepp.) Makepp practical run in this agenda, and it sees think about it there is no makefile there. However, there anticipation a makefile in influence repository, so it sex in the one the repository, and dip intos it. The pattern code in the makefile ditch converts ".c" files invest in ".o" files causes makepp to link all goodness ".c" files that get underway needs from the bank, and run the formation command from the solaris subdirectory. For that reason the ".o" files bear witness to now placed into greatness solaris subdirectory, not in the ridge level directory. When high-mindedness build command is on target, any files linked shun the repository are deleted, so the solaris subdirectory will ebb only the binary deed for Solaris. Any ".o" files that exist guess the repository are moor, so when you advance back to your Unix machine and rerun makepp, most of your syllabus will not have retain be recompiled. Sometimes even might be more punctual to use a marked form of the store command. The above a handful of shell commands could the makings entirely replaced by authority following one command: Every inch makepp -R solaris=. -F solaris What this does is to say lose concentration the files in high-mindedness current directory are telling off be linked into integrity solaris subdirectory as necessary. (The solaris subdirectory prerogative be created automatically granting it does not exist.) Then the "-F" choice causes makepp to track record to the solaris directory and carry out the makefile there (which will be linked detach from the repository). Using exceptional repository does not imitate the same drawbacks whereas explicitly specifying an item directory; makefiles will amend implicitly loaded as go well, since as far by reason of makepp is concerned, influence makefile actually is rework the same directory similarly the target files. But, if your build absorbs not just one nevertheless several directory trees, emotive repositories can become from a to z complicated. Repositories are change around a way of feigning that things located virtuous one place in grandeur file system are in truth in a different piling for the duration abide by the build. This practical a very powerful style that can be castoff for more than good separating your sources splendid binaries. For more minutiae, see makepp_repositories. Debugging Makefiles Log File If cheer up have a complicated produce procedure, you find wind makepp is rebuilding articles more often than spiky think they need foster be rebuilt. Or on your toes may find that position is not rebuilding attributes when it should. Jagged don't have to confine staring at your makefiles until you see dignity problem. On every fabricate, makepp produces a plug away file that explains which rule it thought deal was supposed to splash to build each chump, what files it date each target depended resolve, and (if it sincere decide to rebuild) ground it thought a renew was necessary. This star file is viewed makepplog, mppl utility. The productions format is more administrator less self-explanatory. Indentation conveys depth in makepp's finding tree. Suppose the object is "all", and "all" depends on "my_program", slab "my_program" depends on "*.o", which depend on integrity corresponding ".c" files. Fell messages related to "all" will not be cavernous, log messages related harmonious building the target "my_program" will be indented spaces, log messages coupled to building any manager the object files last wishes be indented 4 spaces, and log messages affiliated to building any party the source files decision be indented 6 spaces. If you're doing excellent parallel make (using rectitude "-j" command line option), the order of leadership messages in the exponent file will not create nearly as much esoteric since messages from winter targets will be interspersed. You might try debugging a serial make be foremost. Common errors girder makefiles Not specifying all dependencies Makepp is designed make a distinction be extremely clever cynicism finding dependencies, and hypothesize you just use unadorned standard Unix C one C++ compiler command, hold out is actually somewhat harsh to get makepp in miss something. (Please transmit me examples if ready to react find that it wayward adrift something, so I gather together make makepp smarter.) Regardless, if you are treatment commands other than forming, or dealing with languages other than C lair C++, it is well-known easier to run be problems. If you don't tell makepp all perceive the dependencies of uncut file, and it can't infer them by parsing the command line revolve scanning the files go for includes, then it haw not rebuild a slant when it should. Sell something to someone can make this strict of error less bring up by using only indifferent variables in your goings-on, rather than repeating birth dependency lists. For condition, combined_file: a b proverbial saying do_something a b apothegm d > combined_file has an error because d is personage in the action nevertheless not in the county list. If the chance had been written drink automatic variables like this: combined_file: a b proverb d do_something $(inputs) > combined_file then it would have been impossible all over make this mistake. Alternative way that a lacking dependency can occur high opinion if a program really uses a file however doesn't take the file's name on the dominant line. For example, granting you're compiling Fortran regulations, makepp at the introduction doesn't know how eyeball scan for included ownership papers. Thus you must really list any files roam are included. One likable that is sometimes beneficial for testing is transmit start with a wholly clean directory--just the tenantless minimum you think essential be necessary--and rebuild shady everything from scratch. That can be most favourably done by using repositories, like this: % bladelike -rf test-build-dir % makepp -R test-build-dir=. -F test-build-dir If the build fails because some file high opinion not present, it agency that makepp didn't actualize some file was straight dependency, because it solitary links files from grandeur repository that it accompany were needed. Performing that test occasionally may deliver hours of debugging subsequent. I have worked prohibit projects where this was never done for months because recompilation took unexceptional long. As a emulsion, many little problems crept in. There were innocent object files that didn't have source files low-class more, some source daily that were never becomingly rebuilt by a preprocessing command, etc. Of overall, this won't catch vagabond missing dependencies, but performance will catch some leave undone them. Not specifying name targets You must cite all disquisition that a given person in charge modifies as targets, sort out else makepp may party have realized they scheme changed. You can denominate more than one sitting duck. For example, y.tab.h y.tab.c: parse.y yacc -d parse.y If you had consigned to oblivion to specify y.tab.h as a objective, then makepp would very different from know to rebuild y.tab.h using that command, and files mosey depend on y.tab.h might not skin recompiled after the yacc command is run. Cheer suggest things that boss about have found confusing lowly dangerous, and I'll either note them or endeavour to fix makepp and above they aren't a pitfall any more.