[[PageOutline]] = Start hacking in WebKitGTK+ = == HW conditionants == WebKit is such a bahamut that the first thing to take into account is the location we want to use as our working place. Basically, we will be able to compile in two flavors: ''Release'' and ''Debug''. As its name says, the debug compilation mode will keep the debugging symbols. This is handy for debugging but will take longer time in the compilation, will use much more space and will need much more RAM. In addition, the performance may be affected when trying to open a debugging session with GDB. * A local copy of the Git repository will take ~7Gb. * As the GTK port uses for its build ''jhbuild'', the dependencies needed will take ~3Gb. * The objects of a ''Release'' build will take another additional ~1Gb. * The objects of a ''Debug'' build will take another several additional Gbs (approx. amount to be completed). In addition, there may be other factors to get into account: * You may want to speed up your compilation through the usage of ''ccache'' and, therefore, reserve another ~8Gb (with few builds my cache is taking ~3Gb). * You may want to combine WebKitGTK development with ''Epiphany'' development, the reference application using WebKitGTK and the official GNOME web browser. This will take another additional Gbs (approx. amount to be completed). * You may want to do your hacking in a chroot environment so it doesn't interfere with your production distribution. A basic Ubuntu Quantal Quetzal x64 in which to work takes to me ~4Gb. With all this, I would reccommend to start working in a hard drive partition in which we have at least a minimum of '''50Gb''' of free space. In addition, WebKit needs tons of RAM memory and CPU power. If you don't want to get bored waiting for your compilations to end you will need a powerful machine with several cores and Gbs or RAM. Not only that, nowadays hackers usually carry out their job in laptops. As time goes by they become more powerful but still several WebKit hackers get the support of desktop computers to speed up their compilations with the help of distributed compiling tools like ''distcc''. My computer is a [http://www.thinkwiki.org/wiki/Category:X220 Lenovo Thinkpad X220] with a SSD hard drive, 8Gb RAM and a dual-core Intel® Core™ i7-2620M (2.7GHz, 4MB L3 cache). A clean ''Release'' build takes ~1h. You will have to take all of this into consideration before starting to work in WebKit. == Getting the source == This is already explained in the BuildingGtk section and the instructions to use Git in UsingGitWithWebKit but, trying to give straight commands, you most probably would like to use Git as your revision control tool. WebKit actually uses SVN for its official revision control tool but tons of developers use Git and its usage is well supported. {{{ #!sh $ git clone git://git.webkit.org/WebKit.git WebKit }}} As you may also want to keep track of the official SVN repository, let's do: {{{ #!sh $ cd WebKit $ git svn init --prefix=origin/ -T trunk http://svn.webkit.org/repository/webkit $ git config --replace svn-remote.svn.fetch trunk:refs/remotes/origin/master $ git svn fetch }}} Done! You are ready to start using the code. == Compiling == Before even starting to think in compiling we may want to be sure that we won't have to repeat the same huge effort shortly after. Hence, we would like to put into place some [wiki:WebKitGTK/SpeedUpBuild build speeding techniques]. Summarizing, if you are working isolated with a single computer, just start using [wiki:WebKitGTK/SpeedUpBuild#ccache ccache]. If you are in a network in which other computers are available to help on compiling, just start using [wiki:WebKitGTK/SpeedUpBuild#distcc distcc] or some other distributed compiling software like ''icecc''. After you have your settings ready, you can just follow the instructions in BuildingGtk. Basically, you will compile and install the needed dependencies with ''jhbuild'' and will compile WebKitGTK with the default options. There are a couple of things still to be considered: * ''Release'' or ''Debug''? The default compilation will do a ''Release'' build. You may think that it may be worthy to actually do a ''Debug'' build since you are planning to start hacking and make use of ''gdb''. However, a ''Debug'' build will take longer, more hard drive space and more RAM. In addition, running a debug build in ''gdb'' may be a pain. Because of this, most of the WebKit hackers choose to just use a ''Release'' build and make an extensive usage of ''printf'' as debugging tool. Also, there is the possibility to ''tweak'' a ''Release'' build to keep [wiki:WebKitGTK/Debugging#DebuggingWebKitGTK certain debugging helpers] and yet not being a full ''Debug'' build. - In any case, don't worry too much since a ''Release'' and a ''Debug'' build can co-exist as WebKit store the resulting objects in different directories. * You may want to disable the compilation of unneeded pieces for if you are not working on them. For example, you can pass: * Disable SVG: --no-svg * Disable GTK doc: --disable-gtk-doc * Disable WebKit1: --no-webkit1 {{{ #!sh $ Tools/Scripts/build-webkit --gtk --no-svg --disable-gtk-doc --no-webkit1 }}} - You should check all the possible flags to pass to the building script: {{{ #!sh $ Tools/Scripts/build-webkit --help }}} === Compilation issues === If you have strange issues while compiling you can try the following (in no particular order): * If you are using `ccache`, clean it: {{{ #!sh $ ccache -C }}} * If you may be using the `gold` compiler, change `ld` in order to use `ld.bfd` instead of `ld.gold`. Instructions: * Configure `update-alternatives`: {{{ #!sh $ update-alternatives --install "/usr/bin/ld" "ld" "/usr/bin/ld.gold" 20 $ update-alternatives --install "/usr/bin/ld" "ld" "/usr/bin/ld.bfd" 10 }}} - Then choose the preferred one with the following command: {{{ #!sh $ update-alternatives --config ld }}} * Use a `jhbuild` shell and compile with `-j1`. Example with problems compiling `cairo`: {{{ #!sh $ Tools/jhbuild/jhbuild-wrapper --gtk shell $ cd WebKitBuild/Dependencies/Source/cairo-1.12.8/ $ ../../Root/bin/make -j1 $ ../../Root/bin/make install }}} That instructions assume that the configure step was successful in the first place. If you need to repeat all the module build, it's better to do it directly using jhbuild. Never invoke `./configure` manually without parameters if you don't know what you're doing: {{{ #!sh $ Tools/jhbuild/jhbuild-wrapper --gtk buildone -f cairo }}} == Rebuilding == As you code new features and fix bugs you will need to rebuild the sources or dependencies. You have to be careful if you don't want to waste time. You don't want compiled code to be swiped by mistake given the time that it takes to build it. The build result is located in the ''WebKitBuild'' directory. ''Release'' builds will be place under ''WebKitBuild/Release''' while Debug builds will be placed under ''WebKitBuil/Debug''. As you should know by now, building dependencies will typically be gotten with the help of ''jhbuild''. The default command for this, as explained in BuildingGtk is: {{{ #!sh $ Tools/Scripts/update-webkitgtk-libs }}} This command will clean current dependencies tree. Therefore, if you only want to perform an action on a certain module it would be better to do it directly using jhbuild. For example: {{{ #!sh $ Tools/jhbuild/jhbuild-wrapper --gtk buildone -f cairo }}} The result of building the dependencies will be placed under ''WebKitBuild/Dependencies''. Similarly, if we have peformed changes in the code, in BuildingGtk we have seen that the script to perform a build is: {{{ #!sh $ Tools/Scripts/build-webkit --gtk }}} Now, if we want just to manuall build our changes or only certain targets, we can get into the ''jhbuild'' environment with {{{ #!sh $ Tools/jhbuild/jhbuild-wrapper --gtk shell }}} And manually invoke ''make'': {{{ #!sh $ cd WebKitBuild/Release $ make }}} Or, if we just want to rebuild MiniBrowser: {{{ #!sh $ cd WebKitBuild/Release $ make Programs/MiniBrowser }}} === Keeping up to date === WebKkit development happens at a high speed. Most of the changes won't have a real impact on the feature or bug you are actually fixing while usually would mean rebuilding huge parts of the code. Therefore, it is better not to rebase master to our working branch too often. Usually, you would want to rebase your work only when you have completed the task, but be also aware of parallel work that may affect your code. Plan ahead when you'll have a free slot of time in which to rebase and compile again as it will probably take several minutes. == Testing == WebKit provides a really complete set of tets to check the code and your changes. You can get more information about them in WebKitGtkLayoutTests. In addition, you may want to check your changes in an actual application. WebKit provides a dummy browser in which to do so. GTK+ port actually has GtkLauncher, featuring WebKit1 and MiniBrowser, featuring WebKit2. * To run GtkLauncher: {{{ #!sh $ Tools/Scripts/run-launcher --gtk }}} * To run MiniBrowser (WebKit2): {{{ #!sh $ Tools/Scripts/run-launcher --gtk -2 }}} Of course, this can be done also manually from the ''jhbuild'' shell: {{{ #!sh $ Tools/jhbuild/jhbuild-wrapper --gtk shell $ WebKitBuild/Release/Programs/GtkLauncher & $ WebKitBuild/Release/Programs/MiniBrowser & }}} == Debugging == Here you have some [wiki:WebKitGTK/Debugging debugging tips] and also some other tips for [wiki:WebKitGTK/TrackingMemoryErrors tracking memory errors]. == Continuous integration == WebKit continuous integration happens in http://build.webkit.org/. There are a number of ''gardening'' guidelines to help [wiki:WebKitGTK/KeepingTheTreeGreen keeping our build bots green].