This documentation is for WSO2 Carbon 4.2.0. View documentation for the latest release.
Creating a Carbon Kernel Patch - Carbon 4.2.0 - WSO2 Documentation
||
Skip to end of metadata
Go to start of metadata

According to the WSO2 patch application process, the first step is to create a kernel patch by changing the code base and generating JAR files corresponding to those changes. This page explains the public patching model for Carbon kernel patches. These patches can be applied to a Carbon server as explained in Applying a Patch to the KernelNote that patch releases of WSO2 products based on Carbon are done using this public patching model. See Shipping a Kernel Patch with Distribution for details on how a patch is shipped with a product distribution.

Follow the steps given below to create a kernel patch.


Creating a JIRA issue for the kernel patch

Each patch has many fixes, so for each fix, you create a separate issue in the Carbon project of the public WSO2 JIRA database (http://wso2.org/jira). Be sure that each JIRA issue provides detailed information about that fix in the patch. Thereafter, add the links of the created JIRA issue to the README.txt file of the patch as described in creating a patch below.

Setting up the development environment

Before you do any development using the Carbon source code, be sure you have met the Installation Prerequisites and that you also have Subversion (SVN) and Apache Maven installed in your environment. You place your kernel patch fix in the kernel/branches/<version-number>/patches directory, which is where all patch-related information is stored for the kernel branch.

Example: Branch in svn/git for Kernel 4.1.0.

After each kernel release, the kernel/branches/<version-number>/patches directory is the only directory that allows commit access.

Creating a patch

  1. Create the relevant patch folder (patch0001) under the kernel/branches/<version-number>/patches directory in svn/git.

  2. Use the SVN copy function to copy the relevant components that have to be fixed into your patch0001 folder.

    Keep in mind the following:
    • When creating fixes, API changes are not allowed.

    • This patching process is only allowed in the repository/component/plugins directory.

  3. Add the following .txt files to the patch0001 directory: 

    File  NameDescription
    READMEThis file includes the following details:
    1. Patch ID (for example, WSO2-CARBON-PATCH-<version>-001).
    2. Kernel version (for example, WSO2 CARBON<version>).
    3. Associated public JIRAs.
    4. Details about the fix.
    LICENSE

    Details about Apache License 2.0 (http://www.apache.org/licenses/LICENSE-2.0.html)

    wso2carbon-versionDetails about the Carbon server version (for example, WSO2 Carbon Framework v<version>patch001)

    The patch directory structure should now look like this:

  4. If you are patching a component at the dependency level, create the dependencies directory (if it does not already exist) under kernel/branches/<version-number>/patches/patch0001.
  5. Use the SVN copy function to copy into the dependencies folder the relevant dependency component that needs to be patched.
  6. If the dependency includes an Orbit POM, create an orbit directory (if it does not already exist) under kernel/branches/<version-number>/patches/patch0001.
  7. Use the SVN copy function to copy into the orbit folder the relevant orbit POM component that needs to be patched.

  8. In the kernel/branches/<version-number>/patches/patch0001/distribution directory, create the assembly file (bin.xml), if it has not already been created. This file is responsible for aggregating and creating the patch file, that is, to copy the license, README, and wso2carbon-version.txt files along with the relevant, patched JARs from the target directories to the composite patch directory.

    Example assembly file: 

    <assembly>
        <includeBaseDirectory>true</includeBaseDirectory>
        <baseDirectory></baseDirectory>
        <id>carbon-patch-0001</id>
        <formats>
            <format>zip</format>
        </formats>
        <files>
            <file>
                <source>../org.wso2.carbon.core/target/org.wso2.carbon.core-4.1.0.jar</source>
                <outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001/patch0001</outputDirectory>
                <destName>org.wso2.carbon.core_4.1.0.jar</destName>
                <fileMode>644</fileMode>
            </file>
            <file>
                <source>../wso2carbon-version.txt</source>
                <outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001</outputDirectory>
                <fileMode>644</fileMode>
            <filtered>true</filtered>
            </file>
            <file>
                <source>../README.txt</source>
                <outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001</outputDirectory>
                <fileMode>644</fileMode>
            <filtered>true</filtered>
            </file>
            <file>
                <source>../LICENCE.txt</source>
                <outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001</outputDirectory>
                <fileMode>644</fileMode>
                <filtered>true</filtered>
            </file>
        </files>
    </assembly>

    For more information on the Maven assembly plugin, go to http://maven.apache.org/plugins/maven-assembly-plugin/.  
    For function definitions, go to http://maven.apache.org/plugins/maven-assembly-plugin/assembly.html.

  9. Create the root POM  file in the kernel/branches/<version-number>/patches/patch0001/distribution directory, if it has not already been created. The root POM file builds the whole structure and calls the assembly plugin. When the POM file is created, first the components are built, and then the assembly plugin is called to create the patch ZIP file under the distribution directory.

    Example root POM file:

    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    
        <parent>
            <groupId>org.wso2.carbon</groupId>
            <artifactId>carbon-parent</artifactId>
            <version>4.1.0</version>
            <relativePath>../../parent/pom.xml</relativePath>
        </parent>
    
        <modelVersion>4.0.0</modelVersion>
        <artifactId>WSO2-CARBON-PATCH-4.1.0</artifactId>
        <version>0001</version>
        <packaging>pom</packaging>
        <name>Distribution-Aggregate</name>
        <description>WSO2 Carbon Patch 0001 - Distribution</description>
        <url>http://wso2.org</url>
    
        <modules>
        <module>org.wso2.carbon.core</module>
        </modules>
    
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-assembly-plugin</artifactId>
                    <version>2.4</version>
                    <executions>
                        <execution>
                            <id>2-dist</id>
                            <phase>package</phase>
                            <goals>
                                <goal>attached</goal>
                            </goals>
                            <configuration>
                                <outputDirectory>distribution</outputDirectory>
                                <descriptors>
                                    <descriptor>${basedir}/bin.xml</descriptor>
                                </descriptors>
                                <appendAssemblyId>false</appendAssemblyId>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </project>

Sample patch directory

For example, if you want to patch the Axis2 kernel along with some other Carbon component (e.g., org.wso2.carbon.xxxx), the file structure should be as follows:

Patch 0001 to Patch 0100 is the numbering format reserved for kernel patches. These patches can be applied to a running production environment as described in Applying a Patch to the Kernel. Also, these patches can be shipped with a product distribution as described in Shipping a Kernel Patch with Distribution.

  • No labels