| blob | 55f510dba49b7e760c5b9013e5373db7d10c92f3 |
8 @ for traditional meaning, build-pkg is consisted by several parts:
9 # build-files-params-setting(deps/srclist/paramlist/instpkglist/doclist/
10 subpkglist)
11 # info(cmdlist/build/author/srcpkg/dep)
12 # env-chk(cmd/lib/hdr)
13 # compile
14 # doc(mandoc/umdoc/webdoc)
15 # intl
16 # test(loop/perf)
17 # install/pkg
18 # dist-pub
20 @ for new features, build-pkg is consisted by several parts:
21 # misc-note-category
22 # demand-feature-mngr
23 # devtask
24 # bug-mngr
25 # auto-gen
26 # code-mngr
27 # code-check
28 # multi-task-machine
29 #
32 # introduction
33 ==============
35 paramters in IDE is edited by graphical form, absolute data from it, and
36 category them, and let then orgnized in easy and familar form.
37 eg: makefile orgnize src file to be compiled as a variable with string list.
38 in build-pkg, this list write into a single file that easy to be edited, and we
39 can use program edit it easily, rather then it is mixed in a config file.
40 those things should be writing in a single file:
42 @ c-src-file.list: src file list.
43 @ CFLAGS-INCPATH.list: include path list.
44 @ CFLAGS-DEF.list: cmdline macro define list.
45 @ inc-pkg.list: external dependence pkg list.
46 @ LDFLAGS-LIB.list: lib name list for a specified dest object.
47 @ LDFLAGS-LIBPATH.list: lib path list.
49 those list file is usually displayed in IDE as a tree/listview controller.
50 and other usefuall and general paramters stored in XXX-MISC.imi in XXFLAGS_YYY
51 variables.
52 it is more easy to integrated in other develop environment, graphical or
53 terminal.
56 another feature in makefile is src/dest alias with cmd executing. in build-pkg,
57 it is implemented in a function. use ${var//src/dst}, or sed cmd, is more power-full
58 then $(wildcast XX,XX,XX) $(patsubst XX,XX,XX) and so on in makefile.
61 they are the compile paramter files for src-pkg building.
63 @ trim paramter by different kinds. different kind of paramters stored in
64 different files, every paramter writen in one line. it's easy to edit by shell
65 script.
66 @ especially for some repeated paramter, such as lib path, include path,
67 src-file list, and so on. it can be processed with script easily.
68 Makefile process repeated paramters or repeated command executing by tag or
69 rule or $(patsubst). pkg-build put the repeated part into a .list file.
70 @ it's similar with some IDE, setting for scrope of project, executable, and
71 some particular src files.
72 @ settings.imi contains totoal config info beyound .list files. it's easy for
73 reading. and it can be parsed into diffrent dir and files, it's easy for shell
74 script processing.
75 @
78 # directory and files
79 =====================
81 dep: it store file of xxx.pc referenced in paramter setting.
83 dest: dest config info dir.
84 dest/dest-general: settings for current project. files in it will be included in
85 a actual DEST config file for project paramter setting.
86 if the global paramter should be re-defined, comment the statement of
87 include. if the dest need paramters beyound global defination, append it in
88 dir of "DEST/DEST-<name>/*.list".
89 for single paramter append, add it to CFLAGS.imi or LDFLAGS.imi.
90 for single src file compile parmaters, make the similar dir as "DEST-<name>",
91 and write it to the corresponding config file.
92 dest/dest-general/*.imi: single paramter for compile or link.
93 dest/dest-general/*.list: a set of similar paramters used for compile or link.
94 dest/dest-general/inc-pkg.list: it's different with LDFLAGS-XXX.list, it's the
95 pkg name list with <name>.pc. build function will generate -l paramter for
96 compile.
98 dest/dest-<name>: config info for dest of <name>.
99 dest/dest-<name>/*.list: same as the files in dest-general.
100 dest/dest-<name>/build.imi: main config file for dest compilation. it include
101 files in dest/dest-general/*, include the files in current dir, and also the
102 directorys under dest/dest-<name>/src/<src-file-name>.
103 dest/dest-<name>/CFLAGS.imi: paramters of CFLAGS in totoal.
104 dest/dest-<name>/LDFLAGS.imi: paramters of LDFLAGS in totoal.
105 dest/dest-<name>/c-src.list: src file list for current dest building.
106 dest/dest-<name>/obj.list: obj file list for current dest building. it's used
107 for every dest building in DESTS normally.
108 under dest/dest-<name>/src/<src-file-name>/: it's a path name with dir prefix in
109 dir of 'src'. it's similar with dest/dest-<name>/ for paramters of single src
110 file .
112 dests/dests-<name>: config info for lots of dest with a totoal name <name>. it
113 compile src file to an executable file. if you want to append some public src
114 files, compile them as a .o/.a/.so dest first.
116 pkg: install pkg info dir.
117 pkg-<name>-<subname>: a src-pkg generate lots of installable pkgs. this dir is
118 the subname in src-pkg. installable pkgs can be scalable.
120 shlib: it store code for building.
121 tasklib: some private task for building. such as *.def => *.c.
125 # config
126 ========
128 config file define variables with 'CONFIG_' prefix. it is used:
130 @ in config.h, and used in code by '#ifdef' or '#if'.
131 @ defined as a marcro, and used in compile paramter of '-DCONFIG_XXX'.
132 @ for switch of some feature src file, it is used as:
133 TUILIB_C_SRC_${CONFIG_XXX}+="src/tuisrc/matrix.c"
134 in c-src.list.
135 if CONFIG_XXX is defined as 'y' or 'Y'. it will be compiled in list of
136 TUILIB_C_SRC_Y as TUILIB_C_SRC.
137 if CONFIG_XXX is defined as 'n' or 'N'. it will not be compiled.
138 TUILIB_C_SRC_LIST="${TUILIB_C_SRC} ${TUILIB_C_SRC_y} ${TUILIB_C_SRC_Y}"
139 if some files need to be compile by complex expression of '#if' statement in
140 Makefile, process many CONFIG_XXX variable in a function, and define other
141 variables for some particular src file config.
142 it's the same for other compile paramters, such as some optimize paramter
143 switch by 'CFLAGS_${CONFIG_XXX}+="-O2"'.
144 @
147 # testing
148 =========
150 testing work can be done by script or executable file.
151 for integrated testing, put test program src-file in dir of 'testing/src'.
152 for unit testing, put test program src-file in dir same as it's code. named
153 it as 'xxx_test.c', and append them to 'dests' of 'testing'. it put a module
154 files of function feature in the same dir.
155 for some unit testing, some feature is not treated as a module, it's just
156 code block, and it will not be re-used. put unit src-files in 'testing/src'.
159 # code generation in build
160 ==========================
162 some code should be generated when it was build. it uses utility programs to
163 do this work. some times, it's a script program, some times it's a binary
164 program.
165 if it's a binary program with src, put it in dir of 'utils' or 'supports' or
166 'tools'. if it's a script program, put it in dir of 'scripts'. i think the
167 name of 'supports' is more suitable, it means programs for building.
168 for code generation, it's the similar work as compilation, which include src
169 file and dest file.
172 # general operation
173 ===================
175 some operation is too complex by writing config files. for example, version
176 file generate, config file generate, code pre-processing, there are many work
177 before source code building. if we append a dest or dests to generate them,
178 it's too complex to read.
179 sometimes, we can write building command in a function, and invoke it before
180 building.
181 version.h and config.h is single file processing, it's different with lots
182 of src file pre-processing. write them by a function.
183 file of '*.def' is the src file for builtin .c src-code. for many repeated
184 src-file pre-processing, it's suitable to append a dests in project.