mirror of
https://github.com/krzysztofzablocki/Sourcery.git
synced 2026-04-07 19:17:40 +00:00
art-divin
434 lines
23 KiB
HTML
434 lines
23 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<title>Usage Reference</title>
|
||
<link rel="stylesheet" type="text/css" href="css/jazzy.css" />
|
||
<link rel="stylesheet" type="text/css" href="css/highlight.css" />
|
||
<meta charset='utf-8'>
|
||
<script src="js/jquery.min.js" defer></script>
|
||
<script src="js/jazzy.js" defer></script>
|
||
|
||
<script src="js/lunr.min.js" defer></script>
|
||
<script src="js/typeahead.jquery.js" defer></script>
|
||
<script src="js/jazzy.search.js" defer></script>
|
||
</head>
|
||
<body>
|
||
<a title="Usage Reference"></a>
|
||
<header>
|
||
<div class="content-wrapper">
|
||
<p><a href="index.html">Sourcery 2.2.6 Docs</a> (100% documented)</p>
|
||
<p class="header-right"><a href="https://github.com/krzysztofzablocki/Sourcery"><img src="img/gh.png"/>View on GitHub</a></p>
|
||
<p class="header-right">
|
||
<form role="search" action="search.json">
|
||
<input type="text" placeholder="Search documentation" data-typeahead>
|
||
</form>
|
||
</p>
|
||
</div>
|
||
</header>
|
||
<div class="content-wrapper">
|
||
<p id="breadcrumbs">
|
||
<a href="index.html">Sourcery Reference</a>
|
||
<img id="carat" src="img/carat.png" />
|
||
Usage Reference
|
||
</p>
|
||
</div>
|
||
<div class="content-wrapper">
|
||
<nav class="sidebar">
|
||
<ul class="nav-groups">
|
||
<li class="nav-group-name">
|
||
<a href="Guides.html">Guides</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a href="installing.html">Installing</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="usage.html">Usage</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="writing-templates.html">Writing templates</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a href="Examples.html">Examples</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a href="equatable.html">Equatable</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="hashable.html">Hashable</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="enum-cases.html">Enum cases</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="lenses.html">Lenses</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="mocks.html">Mocks</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="codable.html">Codable</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Protocols/Diffable.html">Diffable</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="diffable.html">Diffable</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="linuxmain.html">LinuxMain</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="decorator.html">Decorator</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a href="Types.html">Types</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Types.html">Types</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Type.html">Type</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Protocol.html">Protocol</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Class.html">Class</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Struct.html">Struct</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Enum.html">Enum</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/EnumCase.html">EnumCase</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/AssociatedValue.html">AssociatedValue</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/AssociatedType.html">AssociatedType</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Variable.html">Variable</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Method.html">Method</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/MethodParameter.html">MethodParameter</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Subscript.html">Subscript</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/TypeName.html">TypeName</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/TupleType.html">TupleType</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/TupleElement.html">TupleElement</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/ArrayType.html">ArrayType</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/DictionaryType.html">DictionaryType</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/ClosureType.html">ClosureType</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/GenericType.html">GenericType</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/GenericTypeParameter.html">GenericTypeParameter</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Attribute.html">Attribute</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/ProtocolComposition.html">ProtocolComposition</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a href="Other%20Classes.html">Other Classes</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Actor.html">Actor</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/ClosureParameter.html">ClosureParameter</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/DiffableResult.html">DiffableResult</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/GenericParameter.html">GenericParameter</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/GenericRequirement.html">GenericRequirement</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/GenericRequirement/Relationship.html">– Relationship</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Import.html">Import</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/Modifier.html">Modifier</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Classes/SetType.html">SetType</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a href="Other%20Enums.html">Other Enumerations</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a href="Enums/Composer.html">Composer</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a href="Other%20Extensions.html">Other Extensions</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a href="Extensions/Array.html">Array</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Other%20Extensions.html#/c:@M@SourceryRuntime@objc(cs)BytesRange">BytesRange</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Other%20Extensions.html#/c:@M@SourceryRuntime@objc(cs)FileParserResult">FileParserResult</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Extensions/String.html">String</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Extensions/StringProtocol.html">StringProtocol</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Extensions/Typealias.html">Typealias</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a href="Other%20Protocols.html">Other Protocols</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a href="Protocols/Annotated.html">Annotated</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Protocols/Definition.html">Definition</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Protocols/Documented.html">Documented</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Protocols/Typed.html">Typed</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="nav-group-name">
|
||
<a href="Other%20Typealiases.html">Other Type Aliases</a>
|
||
<ul class="nav-group-tasks">
|
||
<li class="nav-group-task">
|
||
<a href="Other%20Typealiases.html#/s:15SourceryRuntime11Annotationsa">Annotations</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Other%20Typealiases.html#/s:15SourceryRuntime13Documentationa">Documentation</a>
|
||
</li>
|
||
<li class="nav-group-task">
|
||
<a href="Other%20Typealiases.html#/s:15SourceryRuntime0A8Modifiera">SourceryModifier</a>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</nav>
|
||
<article class="main-content">
|
||
<section>
|
||
<section class="section">
|
||
|
||
<h2 id='usage' class='heading'>Usage</h2>
|
||
|
||
<p>Sourcery is a command line tool, you can either run it manually or in a custom build phase using following command:</p>
|
||
<pre class="highlight plaintext"><code>$ ./sourcery --sources <sources path> --templates <templates path> --output <output path>
|
||
</code></pre>
|
||
<div class="aside aside-note">
|
||
<p class="aside-title">Note</p>
|
||
<p>this command may be different depending on the way in which you installed Sourcery (see <a href="installing.html">Installing</a>)</p>
|
||
|
||
</div>
|
||
<h3 id='command-line-options' class='heading'>Command line options</h3>
|
||
|
||
<ul>
|
||
<li><code>--sources</code> - Path to a source swift files. You can provide multiple paths using multiple <code>--sources</code> option.</li>
|
||
<li><code>--templates</code> - Path to templates. File or Directory. You can provide multiple paths using multiple <code>--templates</code> options.</li>
|
||
<li><code>--output</code> [default: current path] - Path to output. File or Directory.</li>
|
||
<li><code>--config</code> [default: current path] - Path to config file. File or Directory. See <a href="usage.html#configuration-file">Configuration file</a>.</li>
|
||
<li><code>--args</code> - Additional arguments to pass to templates. Each argument can have explicit value or will have implicit <code>true</code> value. Arguments should be separated with <code>,</code> without spaces (i.e. <code>--args arg1=value,arg2</code>) or should be passed one by one (i.e <code>--args arg1=value --args arg2</code>). Arguments are accessible in templates via <code>argument.name</code>. To pass in string you should use escaped quotes (<code>\"</code>) .</li>
|
||
<li><code>--watch</code> [default: false] - Watch both code and template folders for changes and regenerate automatically.</li>
|
||
<li><code>--verbose</code> [default: false] - Turn on verbose logging</li>
|
||
<li><code>--quiet</code> [default: false] - Turn off any logging, only emit errors</li>
|
||
<li><code>--disableCache</code> [default: false] - Turn off caching of parsed data</li>
|
||
<li><code>--prune</code> [default: false] - Prune empty generated files</li>
|
||
<li><code>--version</code> - Display the current version of Sourcery</li>
|
||
<li><code>--help</code> - Display help information.</li>
|
||
<li><code>--cacheBasePath</code> - Path to Sourcery internal cache (available only in configuration file)</li>
|
||
<li><code>--parseDocumentation</code> [default: false] - Include documentation comments for all declarations.</li>
|
||
</ul>
|
||
|
||
<p>Use <code>--help</code> to see the list of all available options.</p>
|
||
<h3 id='configuration-file' class='heading'>Configuration file</h3>
|
||
|
||
<p>You can also provide arguments using configuration file. Some of the configuration features (like excluding files) are only
|
||
available when using configuration file. You provide path to this file using <code>--config</code> command line option.
|
||
If you provide a path to a directory Sourcery will search for a file <code>.sourcery.yml</code> in this directory. You can also provide
|
||
a path to config file itself. By default Sourcery will search for <code>.sourcery.yml</code> in your current path.</p>
|
||
|
||
<p>Configuration file should be a valid Yaml file, like this:</p>
|
||
<pre class="highlight yaml"><code><span class="na">sources</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><sources path></span> <span class="c1"># you can provide either single path or several paths using `-`</span>
|
||
<span class="pi">-</span> <span class="s"><sources path></span>
|
||
<span class="na">templates</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><templates path></span> <span class="c1"># as well as for templates</span>
|
||
<span class="pi">-</span> <span class="s"><templates path></span>
|
||
<span class="na">output</span><span class="pi">:</span>
|
||
<span class="s"><output path></span> <span class="c1"># note that there is no `-` here as only single output path is supported</span>
|
||
<span class="na">args</span><span class="pi">:</span>
|
||
<span class="na"><name></span><span class="pi">:</span> <span class="s"><value></span>
|
||
</code></pre>
|
||
<h4 id='multiple-configurations' class='heading'>Multiple configurations</h4>
|
||
|
||
<p>You can pass multiple paths to configuration files using multiple <code>--config</code> command line options.
|
||
Single configuration file can contain multiple configurations under root <code>configurations</code> key:</p>
|
||
<pre class="highlight yaml"><code><span class="na">configurations</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="na">sources</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><sources path></span>
|
||
<span class="pi">-</span> <span class="s"><sources path></span>
|
||
<span class="na">templates</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><templates path></span>
|
||
<span class="na">output</span><span class="pi">:</span> <span class="s"><output path></span>
|
||
<span class="na">args</span><span class="pi">:</span>
|
||
<span class="na"><name></span><span class="pi">:</span> <span class="s"><value></span>
|
||
<span class="na"><name></span><span class="pi">:</span> <span class="s"><value></span>
|
||
<span class="pi">-</span> <span class="na">sources</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><sources path></span>
|
||
<span class="pi">-</span> <span class="s"><sources path></span>
|
||
<span class="na">templates</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><templates path></span>
|
||
<span class="na">output</span><span class="pi">:</span> <span class="s"><output path></span>
|
||
<span class="na">args</span><span class="pi">:</span>
|
||
<span class="na"><name></span><span class="pi">:</span> <span class="s"><value></span>
|
||
<span class="na"><name></span><span class="pi">:</span> <span class="s"><value></span>
|
||
</code></pre>
|
||
|
||
<p>This will be equivalent to running Sourcery separately for each of the configurations. In watch mode Sourcery will observe changes in the paths from all the configurations.</p>
|
||
<h4 id='child-configurations' class='heading'>Child configurations</h4>
|
||
|
||
<p>You can specify a child configurations by using the <code>child</code> key:</p>
|
||
<pre class="highlight yaml"><code><span class="na">configurations</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="na">child</span><span class="pi">:</span> <span class="s">./.child_config.yml</span>
|
||
<span class="pi">-</span> <span class="na">child</span><span class="pi">:</span> <span class="s">Subdirectory/.another_child_config.yml</span>
|
||
</code></pre>
|
||
|
||
<p>Sources will be resolved relative to the child config paths.</p>
|
||
<h4 id='sources' class='heading'>Sources</h4>
|
||
|
||
<p>You can provide sources using paths to directories or specific files.</p>
|
||
<pre class="highlight yaml"><code><span class="na">sources</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><sources dir path></span>
|
||
<span class="pi">-</span> <span class="s"><source file path></span>
|
||
</code></pre>
|
||
|
||
<p>Or you can provide project which will be scanned and which source files will be processed. You can use several <code>project</code> or <code>target</code> objects to scan multiple targets from one project or to scan multiple projects. You can provide paths to XCFramework files if your target has any and you want to process their <code>swiftinterface</code> files.</p>
|
||
<pre class="highlight yaml"><code><span class="na">project</span><span class="pi">:</span>
|
||
<span class="na">file</span><span class="pi">:</span> <span class="s"><path to xcodeproj file></span>
|
||
<span class="na">target</span><span class="pi">:</span>
|
||
<span class="na">name</span><span class="pi">:</span> <span class="s"><target name></span>
|
||
<span class="na">module</span><span class="pi">:</span> <span class="s"><module name> //required if different from target name</span>
|
||
<span class="na">xcframeworks</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><path to xcframework file></span>
|
||
<span class="pi">-</span> <span class="s"><path to xcframework file></span>
|
||
</code></pre>
|
||
|
||
<p>You can also provide a Swift Package which will be scanned. Source files will be scanned based on the package’s <code>path</code> and <code>exclude</code> options.</p>
|
||
<pre class="highlight yaml"><code><span class="na">package</span><span class="pi">:</span>
|
||
<span class="na">path</span><span class="pi">:</span> <span class="s"><path to to the Package.swift root directory></span>
|
||
<span class="na">target</span><span class="pi">:</span> <span class="s"><target name></span>
|
||
</code></pre>
|
||
|
||
<p>Multiple targets:</p>
|
||
<pre class="highlight yaml"><code><span class="na">package</span><span class="pi">:</span>
|
||
<span class="na">path</span><span class="pi">:</span> <span class="s"><path to to the Package.swift root directory></span>
|
||
<span class="na">target</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><target name></span>
|
||
<span class="pi">-</span> <span class="s"><target name></span>
|
||
</code></pre>
|
||
<h4 id='excluding-sources-or-templates' class='heading'>Excluding sources or templates</h4>
|
||
|
||
<p>You can specify paths to sources files that should be scanned using <code>include</code> key and paths that should be excluded using <code>exclude</code> key. These can be directory or file paths.</p>
|
||
<pre class="highlight yaml"><code><span class="na">sources</span><span class="pi">:</span>
|
||
<span class="na">include</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><sources path to include></span>
|
||
<span class="pi">-</span> <span class="s"><sources path to include></span>
|
||
<span class="na">exclude</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><sources path to exclude></span>
|
||
<span class="pi">-</span> <span class="s"><sources path to exclude></span>
|
||
</code></pre>
|
||
|
||
<p>You can also specify path to include and exclude for templates.
|
||
When source is a project you can use <code>exclude</code> key to exclude some of its source files.</p>
|
||
<pre class="highlight yaml"><code><span class="na">project</span><span class="pi">:</span>
|
||
<span class="na">file</span><span class="pi">:</span> <span class="s">...</span>
|
||
<span class="na">target</span><span class="pi">:</span> <span class="s">...</span>
|
||
<span class="na">exclude</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s"><sources path></span>
|
||
<span class="pi">-</span> <span class="s"><sources path></span>
|
||
</code></pre>
|
||
<h4 id='output' class='heading'>Output</h4>
|
||
|
||
<p>You can specify the output file using <code>output</code> key. This can be a directory path or a file path. If it’s a file path, all generated content will be written into this file. If it’s a directory path, for each template a separate file will be created with <code>TemplateName.generated.swift</code> name.</p>
|
||
<pre class="highlight yaml"><code><span class="na">output</span><span class="pi">:</span>
|
||
<span class="s"><output path></span>
|
||
</code></pre>
|
||
|
||
<p>Alternatively you can use <code>path</code> key to specify output path.</p>
|
||
<pre class="highlight yaml"><code><span class="na">output</span><span class="pi">:</span>
|
||
<span class="na">path</span><span class="pi">:</span> <span class="s"><output path></span>
|
||
</code></pre>
|
||
|
||
<p>You can use optional <code>link</code> key to automatically link generated files to some target.</p>
|
||
<pre class="highlight yaml"><code><span class="na">output</span><span class="pi">:</span>
|
||
<span class="na">path</span><span class="pi">:</span> <span class="s"><output path></span>
|
||
<span class="na">link</span><span class="pi">:</span>
|
||
<span class="na">project</span><span class="pi">:</span> <span class="s"><path to the xcodeproj to link to></span>
|
||
<span class="na">target</span><span class="pi">:</span> <span class="na"><name of the target to link to> // or targets</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">target1</span><span class="pi">,</span> <span class="nv">target2</span><span class="pi">,</span> <span class="nv">...</span><span class="pi">]</span>
|
||
<span class="na">group</span><span class="pi">:</span> <span class="s"><group in the project to add files to> // by default files are added to project's root group</span>
|
||
</code></pre>
|
||
<div class="aside aside-note">
|
||
<p class="aside-title">Note</p>
|
||
<p>Paths in configuration file are by default relative to configuration file path. If you want to specify absolute path start it with <code>/</code>.</p>
|
||
|
||
</div>
|
||
|
||
</section>
|
||
</section>
|
||
<section id="footer">
|
||
<p>Copyright © 2016-2021 Pixle. All rights reserved.</p>
|
||
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="noopener" rel="external">jazzy ♪♫ v0.14.0</a>, a <a class="link" href="https://realm.io" target="_blank" rel="noopener" rel="external">Realm</a> project.</p>
|
||
</section>
|
||
</article>
|
||
</div>
|
||
</body>
|
||
</html>
|