Rev 5568 | Details | Compare with Previous | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
5098 | clevermous | 1 | Most programs in the repository are regularly and automatically compiled |
2 | by the autobuild server, compiled binaries are available at |
||
3 | http://builds.kolibrios.org. The autobuild server uses the build system Tup, |
||
4 | data for it are located in files named Tupfile.lua over the repository. |
||
5 | |||
6 | ------------------------------------------------------------------------------- |
||
7 | |||
8 | Q1. I want to build one program and I don't want to know anything about Tup. |
||
9 | Q2. I want to build one program using Tup. |
||
10 | Q3. I want to add a program to the autobuild. |
||
11 | Q4. I want to build the entire system. |
||
12 | Q5. I'm sure that I want to build the entire system. |
||
13 | The autobuild server does this, after all. |
||
14 | Q6. I don't want to keep a zoo of compilers and tools required for Q5, |
||
15 | but I still want to build as many programs as possible with what I have. |
||
5568 | clevermous | 16 | Q7. I have modified the source code of the kernel, one driver or one program |
17 | and want to test changes. |
||
5098 | clevermous | 18 | |
19 | ------------------------------------------------------------------------------- |
||
20 | |||
21 | Q1. I want to build one program and I don't want to know anything about Tup. |
||
22 | A1. Fine. You will need a corresponding compiler, obviously. |
||
23 | |||
24 | * For a FASM program, get FASM at http://flatassembler.net/download.php. |
||
25 | To compile, find the main .asm file of the program and run |
||
26 | path/to/fasm |
||
27 | The compiler will automatically select the name for output, using |
||
28 | base name of input and extension based on file format. Though, you can |
||
29 | give also output name explicitly, as the second argument. |
||
30 | |||
31 | If the compiler produces an error "file not found" regarding 'lang.inc', |
||
32 | the program can be compiled using different languages of interface. |
||
33 | Create a file 'lang.inc' in the same folder as |
||
34 | lang fix en |
||
35 | Here the last word selects the language. Valid languages are |
||
36 | en, ru, et, it, sp. Not all programs provide all translations, |
||
37 | en should always be available, ru is the most frequent after en. |
||
38 | |||
39 | * For a NASM program, get NASM at http://www.nasm.us/. |
||
40 | To compile, find the main .asm file of the program and run |
||
41 | path/to/nasm -f bin -o |
||
42 | Multi-language is rarely supported in this category, but you could still |
||
43 | see sometimes an error "file not found" regarding 'lang_nasm.inc'. If so, |
||
44 | create a file 'lang_nasm.inc' in the same folder as |
||
45 | %define lang 'en' |
||
46 | Read the entry about fasm for description of valid languages. |
||
47 | |||
48 | * For a c-- program, try to avoid compiling it and instead rewrite the code |
||
49 | in a normal language like assembler or C. If you absolutely need |
||
50 | to compile, note that the compiler has been abandoned long ago, so |
||
51 | don't look for an official site. It is possible to find the compiler |
||
52 | somewhere on http://board.kolibrios.org, but be prepared to several tries |
||
53 | because there are several slightly different compiler versions, not all of |
||
54 | which are able to build all programs. |
||
55 | There is no Linux version, but Windows version runs fine under Wine. |
||
56 | |||
57 | * For a GCC program, get the toolchain at |
||
58 | http://ftp.kolibrios.org/users/Serge/new/Toolchain/. |
||
59 | |||
60 | Under Windows, you need the package with "msys" in name and MinGW; |
||
61 | after installing MinGW, unpack the package to |
||
62 | \MinGW\msys\1.0\home\autobuild\tools\win32, the package assumes |
||
63 | exactly this path. Run MinGW shell. |
||
64 | |||
65 | Under Linux, you need the package with "linux" in name |
||
66 | and runtime library cloog; e.g. for Debian-based distributives |
||
67 | use apt-get install libcloog-isl4. Unpack the package to |
||
68 | /home/autobuild/tools/win32, the package assumes exactly this path. |
||
69 | |||
70 | In both MinGW and Linux, make sure that the command |
||
71 | /home/autobuild/tools/win32/bin/kos32-gcc |
||
72 | invokes the compiler. |
||
73 | |||
74 | If the program uses libraries, you will also need to either compile |
||
75 | them separately or download SDK, if they are included to SDK. |
||
76 | Compiling is ultimately a sequence of calls to kos32-gcc and kos32-ld, |
||
77 | but filling exact parameters can be tricky, so maybe you want to |
||
78 | use Tup - proceed to Q2/A2 - or Make, if a maintainer has provided |
||
79 | Makefile. |
||
80 | |||
81 | * For a MSVC program, get the compiler as a part of Visual Studio, |
||
82 | Express Edition is fine, or as a part of Windows SDK. |
||
5176 | clevermous | 83 | For obvious reasons, there is no Linux version, but the compiler runs fine |
5098 | clevermous | 84 | under Wine. |
85 | |||
86 | If the program uses libraries, you will also need to either compile |
||
87 | them separately or download SDK, if they are included to SDK. |
||
88 | Compiling is ultimately a sequence of calls to cl.exe and link.exe, |
||
89 | but filling exact parameters can be tricky, so maybe you want to |
||
90 | use Tup - proceed to Q2/A2 - or Make, if a maintainer has provided |
||
91 | Makefile. |
||
92 | |||
93 | * For any language, if the program is KolibriOS binary, the compiled binary |
||
94 | can optionally be compiled with kpack. Windows version of kpack |
||
95 | can be downloaded at http://diamond.kolibrios.org/prg/kpack.exe, |
||
96 | Linux version can be compiled from sources at |
||
97 | (repository)/programs/other/kpack/linux. |
||
98 | |||
99 | * The kernel can optionally be compiled with kerpack. |
||
100 | Linux version can be compiled from sources at |
||
101 | (repository)/programs/other/kpack/kerpack_linux. |
||
102 | There is no Windows version. |
||
103 | |||
104 | Q2. I want to build one program using Tup. |
||
105 | A2. You will still need the corresponding compiler as described in Q1/A1. |
||
106 | You will also need Tup, get it at http://gittup.org/tup/index.html. |
||
107 | Make sure that the corresponding compiler is somewhere in PATH |
||
108 | and can be invoked without explicit path. For Linux, note that |
||
109 | all programs are invoked without extension, like |
||
110 | fasm |
||
111 | or |
||
112 | kos32-gcc |
||
113 | with one exception: MSVC linker is invoked as link.exe to avoid conflict |
||
114 | with link from coreutils. Under Linux, c--, cl, link.exe should be scripts |
||
115 | invoking Wine with the corresponding binary. The interaction tup+wine |
||
116 | does not work by default; ultimately, invoking scripts should be like: |
||
117 | c--: WINEDEBUG=-all LD_PRELOAD=/path/to/nosetsid.so /path/to/wine /path/to/C--.exe $* |
||
118 | cl: WINEDEBUG=-all LD_PRELOAD=/path/to/nosetsid.so /path/to/wine /path/to/cl.exe -I/path/to/cl/include $* |
||
119 | link.exe: WINEDEBUG=-all LD_PRELOAD=/path/to/nosetsid.so /path/to/wine /path/to/link.exe $* |
||
120 | where nosetsid.so is compiled as a 32-bit shared library |
||
121 | from C file with one line "int setsid() { return -1; }". |
||
122 | |||
123 | If the program does not use any libraries, run |
||
124 | tup init |
||
125 | in the directory with the program. Then, |
||
126 | tup |
||
127 | without arguments will build the program with default settings. |
||
128 | Subsequent runs will not do anything unless any file that was used |
||
129 | during the compilation - not necessarily the main file - is changed; |
||
130 | after that, the program will be recompiled. |
||
131 | By default, tup will not track files outside the directory with "tup init"; |
||
132 | if tracking files in program directory is not sufficient for you, |
||
133 | consider adding updater.full_deps=1 to tup config - see tup manual |
||
134 | for details, for Linux it requires setting tup as suid root - or extending |
||
135 | tup data to the entire repository as described in Q6/A6. |
||
136 | |||
137 | Settings can be configured using the file tup.config. Look to |
||
138 | tup.config.template in the repository root for complete list; |
||
139 | for most programs, only CONFIG_LANG and CONFIG_KPACK_CMD have effect. |
||
140 | |||
141 | If the program uses libraries or helper files for gcc/msvc and you don't |
||
142 | want to build everything at once like Q6/A6, set |
||
143 | CONFIG_HELPERDIR=. |
||
144 | in tup.config, copy programs/use_gcc.lua or programs/use_msvc.lua |
||
145 | and helpers for used libraries, if any, to the directory of the program. |
||
146 | use_gcc.lua and use_msvc.lua do not require additional configuration; |
||
147 | in helpers for used libraries, set path to library in the first line. |
||
148 | Since copied helpers are local files not for the repository, you may use |
||
149 | absolute pathes specific for your machine. |
||
150 | This was designed so that no repository files need to be modified: |
||
151 | Tupfile.lua for the program is able to use either local helpers when |
||
152 | CONFIG_HELPERDIR is set, or repository helpers when the entire repository |
||
153 | is built. |
||
154 | You will also need compiled libraries. If they are included in SDK, use them. |
||
155 | Otherwise, compile them using the same process. Note that for a library, |
||
156 | "tup init" needs to be called in the library directory with include/ and lib/, |
||
157 | even if Tupfile.lua is present only in src/; libraries will be put in lib/. |
||
158 | |||
159 | Q3. I want to add a program to the autobuild. |
||
160 | A3. Select a program from repository which uses same language and libraries. |
||
161 | Copy Tupfile.lua from that program to your program. |
||
162 | Change names of source and binary files accordingly. |
||
163 | If external files are referenced, correct relative pathes accordingly: |
||
164 | e.g. when programs/develop/libraries/menuetlibc_example/Tupfile.lua |
||
165 | references ../../../use_menuetlibc.lua, it resolves to |
||
166 | programs/use_menuetlibc.lua, if your program is built by |
||
167 | programs/other/super_program/Tupfile.lua, the path should be |
||
168 | ../../use_menuetlibc.lua. Commit. |
||
169 | |||
170 | After that, the program will be built regularly. |
||
171 | To include the binary in kolibri.img or kolibri.iso, add it to one of |
||
172 | lists in data/Tupfile.lua. Select the section corresponding to the used |
||
173 | language so that people who build images without your compiler would still |
||
174 | be able to do so. |
||
175 | |||
176 | Q4. I want to build the entire system. |
||
177 | A4. Why? Even the person who has configured the autobuild server does not build |
||
178 | everything on her computer. |
||
179 | |||
180 | If you want to create your own image of the system, it is much simpler to |
||
181 | start from existing one and modify it, building only what is necessary. |
||
5568 | clevermous | 182 | Look for Q7/A7 for details of that approach. |
5098 | clevermous | 183 | If you don't know how to modify an image, don't expect that the build |
184 | system will magically do it for you. The build system uses mtools for |
||
185 | image manipulation; if you have configured mtools, you can just use them |
||
186 | directly. There are also other ways of image manipulation, which would |
||
187 | be closed for you once you decide to become attached to the build system. |
||
188 | |||
189 | If you want to verify or debug your changes in Q3/A3, it is normally |
||
190 | sufficient to build just what you have changed as in Q2/A2. |
||
191 | To be extra sure, you can build from the repository root as in Q6/A6 |
||
192 | limiting to your compiler and FASM for some helper tasks; |
||
193 | any possible differences between this mode and actions of the autobuild |
||
194 | server are due to environment issues, like Windows vs Linux, |
||
195 | and would not be resolved anyway. |
||
196 | |||
197 | If you just want it, note that the full build requires all compilers |
||
198 | listed in Q1/A1 and Linux. MinGW and Cygwin will not help you. |
||
199 | |||
200 | Q5. I'm sure that I want to build the entire system. |
||
201 | The autobuild server does this, after all. |
||
202 | A5. The autobuild server has one concrete configuration with 64-bit Linux. |
||
203 | The developers are slightly interested in compiling programs in different |
||
204 | systems, but nobody needs portability of actions that only one server |
||
205 | does anyway. |
||
206 | |||
207 | So, don't expect support from developers. Though, here goes the instruction |
||
208 | in interest of completeness. |
||
209 | |||
210 | * Configure all compilers as described in Q2/A2. |
||
211 | * Configure kpack and kerpack as described in Q2/A2. |
||
212 | They are optional for Q2/A2, but required here, |
||
213 | the image just could not contain all programs in unpacked form. |
||
214 | * Configure mtools, so that mformat, mmd and mcopy are somewhere in PATH. |
||
215 | * Configure mkisofs. |
||
216 | * For full duplication of the autobuild server configure build variants: |
||
217 | create directories build-eng, build-rus, ... in the root of repository for |
||
218 | every subdirectory in data/ except data/common. Create files |
||
219 | build-eng/tup.config, build-rus/tup.config, ... with |
||
220 | CONFIG_BUILD_TYPE=eng, rus, ... correspondingly. This will switch |
||
221 | to out-of-tree builds for every variant. If one build type is sufficient |
||
222 | for you, you may skip this step. |
||
223 | * Run |
||
224 | tup init |
||
225 | in the root of repository. |
||
226 | * Run |
||
227 | tup |
||
228 | anywhere inside repository. |
||
229 | * If everything went good, there should be files kolibri.img and kolibri.iso |
||
230 | in every build-* directory. When you want to update, |
||
231 | rerun tup without arguments. |
||
232 | |||
233 | Q6. I don't want to keep a zoo of compilers and tools required for Q5, |
||
234 | but I still want to build as many programs as possible with what I have. |
||
235 | A6. |
||
236 | * Configure all compilers you want to use as described in Q2/A2. |
||
237 | * Create tup.config in the root of repository. Disable all compilers you |
||
238 | don't want to use there; comments in tup.config.template should help you. |
||
239 | * Optionally, configure kpack and kerpack as described in Q2/A2. |
||
240 | * Run |
||
241 | tup init |
||
242 | in the root of repository. |
||
243 | * Run |
||
244 | tup |
||
245 | anywhere inside repository. |
||
5568 | clevermous | 246 | |
247 | Q7. I have modified the source code of the kernel, one driver or one program |
||
248 | and want to test changes. |
||
249 | A7. First, you need to build the corresponding binary as described in Q1/A1 or |
||
250 | Q2/A2. |
||
251 | To test a program, it is sufficient to put it to some place accessible |
||
252 | to the working KolibriOS and just run it from there. Drivers are loaded |
||
9583 | vitalkrilo | 253 | from the folder /rd/1/drivers, which is initialized from kolibri.img, |
5568 | clevermous | 254 | so testing a driver requires either copying the compiled binary to |
255 | /rd/1/drivers manually between KolibriOS startup and loading driver or |
||
256 | inserting the driver to the image kolibri.img outside of KolibriOS. |
||
257 | Testing the kernel or an auto-loading driver requires modifying the image. |
||
258 | |||
259 | There are several possible approaches for writing to kolibri.img. |
||
260 | * From inside KolibriOS, write to /rd/1 and then save the ramdisk image. |
||
261 | * On Linux, there is a package named "mtools", |
||
262 | https://www.gnu.org/software/mtools/ . It can be available in the |
||
263 | repository of your Linux distribution or it can be compiled manually. |
||
264 | Compiling mtools for Windows is not impossible, but not supported either. |
||
265 | Using mtools: |
||
266 | mdir -i kolibri.img [ |
||
267 | lists contents of the given directory of the image or the root directory |
||
268 | if |
||
269 | mcopy -moi kolibri.img |
||
270 | inserts the file |
||
271 | reverse order of the arguments, it extracts the corresponding file. |
||
272 | * On Linux with root privileges, the standard mount command can be used: |
||
273 | mount -t vfat -o loop kolibri.img |
||
274 | maps contents of kolibri.img under the directory |
||
275 | hiding whatever was in |
||
276 | umount |
||
277 | * On Windows with administrator privileges, the driver ImDisk |
||
278 | http://www.ltr-data.se/opencode.html/#ImDisk can be used: |
||
279 | imdisk -a -m A: -t file -f kolibri.img |
||
280 | maps contents of kolibri.img to the virtual disk A:. When done, use |
||
281 | imdisk -d -m A: |