CKReleaser"

This website contains links to software which is either no longer maintained or will be supported only until the end of 2019 (CKFinder 2). For the latest documentation about current CKSource projects, including software like CKEditor 4/CKEditor 5, CKFinder 3, Cloud Services, Letters, Accessibility Checker, please visit the new documentation website.

If you look for an information about very old versions of CKEditor, FCKeditor and CKFinder check also the CKEditor forum, which was closed in 2015. If not, please head to StackOverflow for support.

(Article introduction proof-read and formatted)
m (Minor adjustment)
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
= CKReleaser  =
+
__TOC__
 
CKReleaser is an application that exports CKEditor code, making all changes, replacements, and compilations necessary to build a public release of CKEditor. It is a command line program, with the following execution syntax:
 
CKReleaser is an application that exports CKEditor code, making all changes, replacements, and compilations necessary to build a public release of CKEditor. It is a command line program, with the following execution syntax:
 
<source>
 
<source>
−
ckreleaser [source_dir] [target_dir] [version] [zip_name] [gzip_name]
+
ckreleaser release_file source_dir target_dir version file_name [--run-before-release=script] [-v | --verbose]
−
</source>  
+
</source>
 +
* <code>''release_name''</code> &ndash; path to the CKReleaser configuration file.
 
* <code>''source_dir''</code> &ndash; the path to the development code of CKEditor.  
 
* <code>''source_dir''</code> &ndash; the path to the development code of CKEditor.  
 
* <code>''target_dir''</code> &ndash; the path to the output directory.  
 
* <code>''target_dir''</code> &ndash; the path to the output directory.  
 
* <code>''version''</code> &ndash; the version string used to replace the <code>%VERSION%</code> directive.  
 
* <code>''version''</code> &ndash; the version string used to replace the <code>%VERSION%</code> directive.  
−
* <code>''zip_name''</code> &ndash; the <code>.zip</code> file containing the compressed version of the release.  
+
* <code>''file_name''</code> &ndash; name of the release file to create (without the extension).  
−
* <code>''gzip_name''</code> &ndash; the <code>.tar.gz</code> file containing the compressed version of the release.
+
* <code>--run-before-release=''script''</code> &ndash; (optional) the path to a script that is to be run on source files.
 +
* <code>-v</code> (or <code>--verbose</code>) &ndash; (optional) enables verbose output and displays detailed exception information when an error occurs.
  
−
At the end of the process, the <code>''target_dir''</code> directory will be created and it will contain a directory named <code>release</code>, with the uncompressed version of the release files as well as the distribution files (in <code>.zip</code> and <code>.gzip</code> formats).  
+
At the end of the process, the <code>''target_dir''</code> directory will be created and it will contain a directory named <code>release</code>, with the uncompressed version of the release files as well as the distribution files (in <code>.zip</code> and <code>.tar.gz</code> formats).  
  
 
<note>The execution fails if the <code>''target_dir''</code> already exists.  
 
<note>The execution fails if the <code>''target_dir''</code> already exists.  
 
</note>
 
</note>
  
 +
 +
If you downloaded the latest editor source code from [http://dev.ckeditor.com/browser/CKEditor/trunk CKEditor trunk], you can also run the existing CKReleaser script. Go to the <code>_dev/releaser</code> folder and run the <code>release.bat</code> (for Windows) or <code>release.sh</code> (for Linux) to trigger CKReleaser.
  
 
== Configuration File  ==
 
== Configuration File  ==
 +
CKReleaser uses a configuration file that contains precise information about the tasks to be performed to build a release. The default configuration file for CKEditor is called <code>ckeditor.release</code>. The following are its contents:
 +
<source lang="javascript">
 +
fixLineEnds : true,
  
−
CKReleaser uses a configuration file containing precise information about the tasks to be performed to build a release. The default configuration file for CKEditor is called "ckeditor.release". The following are its contents:
+
ignore :
−
<pre>fixLineEnds&nbsp;: true,
 
−
 
 
−
ignore&nbsp;:  
 
 
[
 
[
 
'_dev',
 
'_dev',
−
'_docs/api',
+
'.svn',
−
'_samples',
+
'.settings',
−
'_source/adapters'
+
'.project',
 +
'.idea'
 
],
 
],
  
−
copy&nbsp;:
+
copy :
 
[
 
[
 
{
 
{
−
source&nbsp;: '_source/lang',
+
source : '_source/lang',
−
target&nbsp;: 'lang',
+
target : 'lang',
−
minify&nbsp;: true
+
minify : true
 
},
 
},
  
 
{
 
{
−
source&nbsp;: '_source/plugins',
+
source : '_source/adapters',
−
target&nbsp;: 'plugins',
+
target : 'adapters',
−
minify&nbsp;: true
+
minify : true
 
},
 
},
  
 
{
 
{
−
source&nbsp;: '_source/tests',
+
source : '_source/plugins',
−
target&nbsp;: 'tests',
+
target : 'plugins',
−
minify&nbsp;: false
+
minify : true,
 +
ignore :
 +
{
 +
sourcePackage : 'ckeditor.pack',
 +
files : 'packages[1].files'
 +
}
 
},
 
},
  
 
{
 
{
−
source&nbsp;: '_source/themes',
+
source : '_source/themes',
−
target&nbsp;: 'themes',
+
target : 'themes',
−
minify&nbsp;: true
+
minify : true
 
}
 
}
 
],
 
],
  
−
packages&nbsp;:
+
rename :
 +
[
 +
],
 +
 
 +
packages :
 
[
 
[
 
'ckeditor.pack'
 
'ckeditor.pack'
 
],
 
],
  
−
documentation&nbsp;:
+
skins :
 
{
 
{
−
config: '_dev/docs_build/docs_build.conf',
+
source : '_source/skins',
−
target: '_docs/api'
+
target : 'skins',
−
},
+
minify : true
−
 
 
−
samples&nbsp;:
 
−
{
 
−
source&nbsp;: '_samples',
 
−
template&nbsp;: '_samples/samples.html'
 
−
},
 
−
 
 
−
skins&nbsp;:
 
−
{
 
−
source&nbsp;: '_source/skins',
 
−
target&nbsp;: 'skins'
 
 
}
 
}
−
</pre>  
+
</source>  
−
Note that the configuration file uses the syntax of a JavaScript literal object declaration. This is intentional, and actually it is also possible to use JavaScript code into the file. The entire file will be then loaded as a literal object declaration and interpreted as JavaScript code.  
+
Note that the configuration file uses the syntax of a JavaScript literal object declaration. This is intentional, and actually it is also possible to use JavaScript code inside the file. The entire file will then be loaded as a literal object declaration and interpreted as JavaScript code.  
  
 
The following are the main entries available in the configuration:  
 
The following are the main entries available in the configuration:  
−
 
+
* <code>fixLineEnds</code> &ndash; indicates that the <code>fixlineends</code> application is to be run in the *output* folder at the end of the process.  
−
*'''fixLineEnds''': indicates that the "fixlineends" application is to be run in the *output* folder at the end of the process.  
+
* <code>ignore</code> &ndash; a list of files and folder paths that are to be ignored by CKReleaser.  
−
*'''ignore''': a list of files and folder paths that are to be ignored by CKReleaser.  
+
* <code>copy</code> &ndash; a list of objects identifying files and folders to be copied to different directories in the release package. The <code>minify</code> argument specifies whether <code>.js</code> and <code>.css</code> files are to be minified when outputting (see "Minification" below).  
−
*'''copy''': a list of objects identifying files and folders to be copied to different directories in the release. The "minify" argument specifies whether .js and .css files are to be minified when outputting (see "Minification" below).  
+
* <code>packages</code> &ndash; a list of configuration files to be executed by CKPackager.  
−
*'''packages''': a list of configuration files to be executed by CKPackager.  
+
* <code>skins</code> &ndash; information about the skins location (see "Skins" below).
−
*'''documentation''': information needed to build the API documentation (see "Documentation" below).
 
−
*'''samples''': information about the _samples folder, including its location and the path to the template file (see "Samples" below).
 
−
*'''skins''': information about the skins location (see "Skins" below).
 
  
 
== Minification  ==
 
== Minification  ==
−
 
+
The process of reducing the size of JavaScript and CSS files by removing spaces, comments, etc. from it is called ''minification''. Several files are to be minified on the output. We are using [[CKEditor_3.x/Developers_Guide/CKPackager|CKPackager]] to minify our source code.
−
The process of reducing the size of JavaScript and CSS files, by removing spaces, comments, etc. from it, is called "Minification". Several files are to be minified on the output. We'll be using CKPackager to minify our source code.
 
−
 
 
−
== Documentation  ==
 
−
 
 
−
The JavaScript API documentation is automatically generated by CKReleaser. It uses JsDoc Toolkit to build a pure HTML reference, extracting the documentation structure and text from the CKEditor source code.
 
−
 
 
−
CKReleaser runs JsDoc Toolkit over a configuration file present in the source directory, outputting it directly to the target directory.
 
−
 
 
−
== Samples  ==
 
−
 
 
−
The "_samples" folder contains a set of examples that show CKEditor in action. The development version of the samples uses a template system to provide a standard output to all samples.
 
−
 
 
−
The template file is called "sample.html". All other .html files located in that folder (source files) contain data used to fill the template.
 
−
 
 
−
The source files are XML files containing several nodes with specific ids that we used to locate the data to be loaded into the template. The following are the possible ids:
 
−
 
 
−
*'''headscript''' (optional): contains sample specific script to be loaded in the &lt;head&gt;.
 
−
*'''styles''' (optional): contains sample specific styles.
 
−
*'''html''': contains the HTML data that effectively represents the sample.
 
−
*'''code''': contains the sample code, used to illustrate the API usage in the sample.
 
−
 
 
−
The template file instead contains &lt;script&gt; tags with the same ids used in the source, that need to be replaced by CKReleaser, filling them with the source data. For example, the following is the original tag, used to embed the "html" data:
 
−
<pre>&lt;script id="html" type="text/javascript"&gt;
 
−
//&lt;![CDATA[
 
−
document.write( CKEDITOR.samples.htmlData );
 
−
//]]&gt;
 
−
&lt;/script&gt;
 
−
</pre>
 
−
CKReleaser '''removes''' the above tag, replacing it with '''the contents''' of the source node with id "html". The "headscript" and "styles" data are special cases, because other than the data contents, the specific &lt;script&gt; and &lt;style&gt; tags must be also included.
 
−
 
 
−
The original source file names must be used for the release version, containing the "template filled" version of each sample. The template file instead will not be part of the release.  
 
  
 
== Skins  ==
 
== Skins  ==
 +
CKEditor skin files consist of a set of CSS, JavaScript, and graphic files, grouped for each skin inside the <code>skins</code> folder.
  
−
The CKEditor skin files consist on a set of CSS and JavaScript files, grouped for each skin inside the skin folder.
+
Other than the JavaScript files minification, there is a particular processing procedure that needs to be performed on the skin files. All <code>@import</code> directives found in the files must be replaced with the effective contents of the imported files, and those imported files are not to be released.  
−
 
 
−
Other than the JavaScript files minification, there is a particular processing that needs to be performed on the skin files. All @import directives found in the files must be replaced with the effective contents of the imported files, and those imported files are not to be released.  
 
  
−
For example, the release of the "default" skin should end up with only two CSS files: editor.css and dialog.css. The former is actually a combination of reset.css, mainui.css, toolbar.css and elementspath.css, which are not released directly instead.  
+
For example, the release of the <code>default</code> skin should end up with only two CSS files: <code>editor.css</code> and <code>dialog.css</code>. The former is actually a combination of <code>reset.css</code>, <code>mainui.css</code>, <code>toolbar.css</code> and <code>elementspath.css</code>, which are not released directly.
  
 
== Directives  ==
 
== Directives  ==
 +
CKReleaser makes a "file by file" copy from the source to the target. As part of this task, it searches for special character combinations (directives) in text files and processes them accordingly.
  
−
CKReleaser makes a "file by file" copy from the source to the target. As part of this task, it search for special character combinations (directives) in text files, processing them accordingly.
+
The following list contains the directives that can be processed:  
−
 
+
* <code>%VERSION%</code> &ndash; the <code>''version''</code> string passed to the CKReleaser execution command.  
−
The following are the processed directives:  
+
* <code>%TIMESTAMP%</code> &ndash; a four-character string with the concatenation of the "Base 36" value of each of the following components of the program execution date and time: year + month + day + hour.  
−
 
+
* <code>%REMOVE_LINE%</code> &ndash; removes the line.  
−
*&nbsp;'''%VERSION%''': the "version" string passed to the CKReleaser execution command.  
+
* <code>%REMOVE_START%</code> and <code>%REMOVE_END%</code> &ndash; removes all lines starting from <code>%REMOVE_START%</code> and ending with <code>%REMOVE_END%</code>, declaration line inclusive.
−
*&nbsp;'''%TIMESTAMP%''': a four characters string containing the concatenation of the "Base 36" value of each of the following components of the program execution date and time: year + month + day + hour.  
 
−
*&nbsp;'''%REMOVE_LINE%''': removes the line.  
 
−
*&nbsp;'''%REMOVE_START%''' and&nbsp;'''%REMOVE_END%''': removes all lines starting from&nbsp;%REMOVE_START% to&nbsp;%REMOVE_END%, declaration line inclusive.
 

Latest revision as of 17:11, 6 December 2011

CKReleaser is an application that exports CKEditor code, making all changes, replacements, and compilations necessary to build a public release of CKEditor. It is a command line program, with the following execution syntax: 

ckreleaser release_file source_dir target_dir version file_name [--run-before-release=script] [-v | --verbose]
  • release_name – path to the CKReleaser configuration file.
  • source_dir – the path to the development code of CKEditor.
  • target_dir – the path to the output directory.
  • version – the version string used to replace the %VERSION% directive.
  • file_name – name of the release file to create (without the extension).
  • --run-before-release=script – (optional) the path to a script that is to be run on source files.
  • -v (or --verbose) – (optional) enables verbose output and displays detailed exception information when an error occurs.

At the end of the process, the target_dir directory will be created and it will contain a directory named release, with the uncompressed version of the release files as well as the distribution files (in .zip and .tar.gz formats).

important note

The execution fails if the target_dir already exists.


If you downloaded the latest editor source code from CKEditor trunk, you can also run the existing CKReleaser script. Go to the _dev/releaser folder and run the release.bat (for Windows) or release.sh (for Linux) to trigger CKReleaser.

Configuration File

CKReleaser uses a configuration file that contains precise information about the tasks to be performed to build a release. The default configuration file for CKEditor is called ckeditor.release. The following are its contents: 

fixLineEnds : true,

ignore :
[
	'_dev',
	'.svn',
	'.settings',
	'.project',
	'.idea'
],

copy :
[
	{
		source : '_source/lang',
		target : 'lang',
		minify : true
	},

	{
		source : '_source/adapters',
		target : 'adapters',
		minify : true
	},

	{
		source : '_source/plugins',
		target : 'plugins',
		minify : true,
		ignore :
		{
			sourcePackage : 'ckeditor.pack',
			files : 'packages[1].files'
		}
	},

	{
		source : '_source/themes',
		target : 'themes',
		minify : true
	}
],

rename :
[
],

packages :
[
	'ckeditor.pack'
],

skins :
{
	source : '_source/skins',
	target : 'skins',
	minify : true
}

Note that the configuration file uses the syntax of a JavaScript literal object declaration. This is intentional, and actually it is also possible to use JavaScript code inside the file. The entire file will then be loaded as a literal object declaration and interpreted as JavaScript code.

The following are the main entries available in the configuration:

  • fixLineEnds – indicates that the fixlineends application is to be run in the *output* folder at the end of the process.
  • ignore – a list of files and folder paths that are to be ignored by CKReleaser.
  • copy – a list of objects identifying files and folders to be copied to different directories in the release package. The minify argument specifies whether .js and .css files are to be minified when outputting (see "Minification" below).
  • packages – a list of configuration files to be executed by CKPackager.
  • skins – information about the skins location (see "Skins" below).

Minification

The process of reducing the size of JavaScript and CSS files by removing spaces, comments, etc. from it is called minification. Several files are to be minified on the output. We are using CKPackager to minify our source code.

Skins

CKEditor skin files consist of a set of CSS, JavaScript, and graphic files, grouped for each skin inside the skins folder.

Other than the JavaScript files minification, there is a particular processing procedure that needs to be performed on the skin files. All @import directives found in the files must be replaced with the effective contents of the imported files, and those imported files are not to be released.

For example, the release of the default skin should end up with only two CSS files: editor.css and dialog.css. The former is actually a combination of reset.css, mainui.css, toolbar.css and elementspath.css, which are not released directly.

Directives

CKReleaser makes a "file by file" copy from the source to the target. As part of this task, it searches for special character combinations (directives) in text files and processes them accordingly.

The following list contains the directives that can be processed:

  • %VERSION% – the version string passed to the CKReleaser execution command.
  • %TIMESTAMP% – a four-character string with the concatenation of the "Base 36" value of each of the following components of the program execution date and time: year + month + day + hour.
  • %REMOVE_LINE% – removes the line.
  • %REMOVE_START% and %REMOVE_END% – removes all lines starting from %REMOVE_START% and ending with %REMOVE_END%, declaration line inclusive.
Retrieved from "https://docs-old.ckeditor.com/index.php?title=CKEditor_3.x/Developers_Guide/CKReleaser&oldid=6773"
This page was last edited on 6 December 2011, at 17:11.