Subversion Repositories Kolibri OS

Rev

Rev 5176 | Blame | Compare with Previous | Last modification | View Log | RSS feed

  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.
  16. Q7. I have modified the source code of the kernel, one driver or one program
  17.     and want to test changes.
  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 <input.asm>
  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 <input.asm> like follows:
  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 <output> <input.asm>
  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 <input.asm> like follows:
  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.
  83.     For obvious reasons, there is no Linux version, but the compiler runs fine
  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.
  182.     Look for Q7/A7 for details of that approach.
  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.
  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
  253.     from the folder /rd/1/drivers/, which is initialized from kolibri.img,
  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 [<dir>]
  267.     lists contents of the given directory of the image or the root directory
  268.     if <dir> is omitted;
  269.         mcopy -moi kolibri.img <file> ::<imgfile>
  270.     inserts the file <file> to the image using the name <imgfile>; with
  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 <dir>
  274.     maps contents of kolibri.img under the directory <dir>, which must exist,
  275.     hiding whatever was in <dir>. When done, use
  276.         umount <dir>
  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:
  282.