38 lines
17 KiB
HTML
38 lines
17 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Package Generation · PkgTemplates.jl</title><link href="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css" rel="stylesheet" type="text/css"/><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link href="../assets/documenter.css" rel="stylesheet" type="text/css"/></head><body><nav class="toc"><h1>PkgTemplates.jl</h1><select id="version-selector" onChange="window.location.href=this.value" style="visibility: hidden"></select><form class="search" action="../search.html"><input id="search-query" name="q" type="text" placeholder="Search docs"/></form><ul><li><a class="toctext" href="../index.html">Home</a></li><li class="current"><a class="toctext" href="package_generation.html">Package Generation</a><ul class="internal"><li><a class="toctext" href="#Template-1"><code>Template</code></a></li><li><a class="toctext" href="#generate-1"><code>generate</code></a></li><li><a class="toctext" href="#Helper-Functions-1">Helper Functions</a></li></ul></li><li><a class="toctext" href="plugins.html">Plugins</a></li><li><a class="toctext" href="plugin_development.html">Plugin Development</a></li><li><a class="toctext" href="licenses.html">Licenses</a></li><li><a class="toctext" href="index.html">Index</a></li></ul></nav><article id="docs"><header><nav><ul><li><a href="package_generation.html">Package Generation</a></li></ul><a class="edit-page" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/docs/src/pages/package_generation.md#L{line}"><span class="fa"></span> Edit on GitHub</a></nav><hr/><div id="topbar"><span>Package Generation</span><a class="fa fa-bars" href="#"></a></div></header><h1><a class="nav-anchor" id="Package-Generation-1" href="#Package-Generation-1">Package Generation</a></h1><p>Creating new packages with <code>PkgTemplates</code> revolves around creating a new <a href="package_generation.html#PkgTemplates.Template"><code>Template</code></a>, then calling <a href="package_generation.html#PkgTemplates.generate"><code>generate</code></a> on it.</p><h2><a class="nav-anchor" id="Template-1" href="#Template-1"><code>Template</code></a></h2><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.Template" href="#PkgTemplates.Template"><code>PkgTemplates.Template</code></a> — <span class="docstring-category">Type</span>.</div><div><pre><code class="language-none">Template(; kwargs...) -> Template</code></pre><p>Records common information used to generate a package. If you don't wish to manually create a template, you can use <a href="package_generation.html#PkgTemplates.interactive_template"><code>interactive_template</code></a> instead.</p><p><strong>Keyword Arguments</strong></p><ul><li><p><code>user::AbstractString=""</code>: GitHub username. If left unset, it will try to take the value of a supplied git config's "github.user" key, then the global git config's value. If neither is set, an <code>ArgumentError</code> is thrown. <strong>This is case-sensitive for some plugins, so take care to enter it correctly.</strong></p></li><li><p><code>host::AbstractString="github.com"</code>: URL to the code hosting service where your package will reside. Note that while hosts other than GitHub won't cause errors, they are not officially supported and they will cause certain plugins will produce incorrect output. For example, <a href="plugins.html#PkgTemplates.AppVeyor"><code>AppVeyor</code></a>'s badge image will point to a GitHub-specific URL, regardless of the value of <code>host</code>.</p></li><li><p><code>license::AbstractString="MIT"</code>: Name of the package license. If an empty string is given, no license is created. <a href="licenses.html#PkgTemplates.available_licenses"><code>available_licenses</code></a> can be used to list all available licenses, and <a href="licenses.html#PkgTemplates.show_license"><code>show_license</code></a> can be used to print out a particular license's text.</p></li><li><p><code>authors::Union{AbstractString, Vector{<:AbstractString}}=""</code>: Names that appear on the license. Supply a string for one author or an array for multiple. Similarly to <code>user</code>, it will try to take the value of a supplied git config's "user.name" key, then the global git config's value, if it is left unset.</p></li><li><p><code>years::Union{Integer, AbstractString}=Dates.year(Dates.today())</code>: Copyright years on the license. Can be supplied by a number, or a string such as "2016 - 2017".</p></li><li><p><code>dir::AbstractString=Pkg.dir()</code>: Directory in which the package will go. Relative paths are converted to absolute ones at template creation time.</p></li><li><p><code>julia_version::VersionNumber=VERSION</code>: Minimum allowed Julia version.</p></li><li><p><code>requirements::Vector{<:AbstractString}=String[]</code>: Package requirements. If there are duplicate requirements with different versions, i.e. ["PkgTemplates", "PkgTemplates 0.1"], an <code>ArgumentError</code> is thrown. Each entry in this array will be copied into the <code>REQUIRE</code> file of packages generated with this template.</p></li><li><p><code>gitconfig::Dict=Dict()</code>: Git configuration options.</p></li><li><p><code>plugins::Vector{<:Plugin}=Plugin[]</code>: A list of <code>Plugin</code>s that the package will include.</p></li></ul></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/template.jl#LL1-L36">source</a><br/></section><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.interactive_template" href="#PkgTemplates.interactive_template"><code>PkgTemplates.interactive_template</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">interactive_template(; fast::Bool=false) -> Template</code></pre><p>Interactively create a <a href="package_generation.html#PkgTemplates.Template"><code>Template</code></a>. If <code>fast</code> is set, defaults will be assumed for all values except username and plugins.</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/template.jl#LL111-L116">source</a><br/></section><h2><a class="nav-anchor" id="generate-1" href="#generate-1"><code>generate</code></a></h2><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.generate" href="#PkgTemplates.generate"><code>PkgTemplates.generate</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">generate(
|
|
pkg_name::AbstractString,
|
|
t::Template;
|
|
force::Bool=false,
|
|
ssh::Bool=false,
|
|
) -> Void</code></pre><p>Generate a package named <code>pkg_name</code> from <code>template</code>.</p><p><strong>Keyword Arguments</strong></p><ul><li><p><code>force::Bool=false</code>: Whether or not to overwrite old packages with the same name.</p></li><li><p><code>ssh::Bool=false</code>: Whether or not to use SSH for the remote.</p></li><li><p><code>backup_dir::AbstractString=""</code>: Directory in which to store the generated package if <code>t.dir</code> is not a valid directory. If left unset, a temporary directory will be created.</p></li></ul><p><strong>Notes</strong></p><p>The package is generated entirely in a temporary directory and only moved into <code>joinpath(t.dir, pkg_name)</code> at the very end. In the case of an error, the temporary directory will contain leftovers, but the destination directory will remain untouched (this is especially helpful when <code>force=true</code>).</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL1-L22">source</a><br/></section><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.generate_interactive" href="#PkgTemplates.generate_interactive"><code>PkgTemplates.generate_interactive</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">generate_interactive(
|
|
pkg_name::AbstractString;
|
|
force::Bool=false,
|
|
ssh::Bool=false,
|
|
backup_dir::AbstractString="",
|
|
fast::Bool=false,
|
|
) -> Void</code></pre><p>Interactively create a template, and then generate a package with it. Arguments and keywords are used in the same way as in <a href="package_generation.html#PkgTemplates.generate"><code>generate</code></a> and <a href="package_generation.html#PkgTemplates.interactive_template"><code>interactive_template</code></a>.</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL127-L139">source</a><br/></section><h2><a class="nav-anchor" id="Helper-Functions-1" href="#Helper-Functions-1">Helper Functions</a></h2><h4><a class="nav-anchor" id="gen_entrypoint-1" href="#gen_entrypoint-1"><code>gen_entrypoint</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.gen_entrypoint" href="#PkgTemplates.gen_entrypoint"><code>PkgTemplates.gen_entrypoint</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">gen_entrypoint(
|
|
dir::AbstractString,
|
|
pkg_name::AbstractString,
|
|
template::Template,
|
|
) -> Vector{String}</code></pre><p>Create the module entrypoint in the temp package directory.</p><p><strong>Arguments</strong></p><ul><li><p><code>dir::AbstractString</code>: The directory in which the files will be generated. Note that this will be joined to <code>pkg_name</code>.</p></li><li><p><code>pkg_name::AbstractString</code>: Name of the package.</p></li><li><p><code>template::Template</code>: The template whose entrypoint we are generating.</p></li></ul><p>Returns an array of generated file/directory names.</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL156-L172">source</a><br/></section><h4><a class="nav-anchor" id="gen_tests-1" href="#gen_tests-1"><code>gen_tests</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.gen_tests" href="#PkgTemplates.gen_tests"><code>PkgTemplates.gen_tests</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">gen_tests(
|
|
dir::AbstractString,
|
|
pkg_name::AbstractString,
|
|
template::Template,
|
|
) -> Vector{String}</code></pre><p>Create the test directory and entrypoint in the temp package directory.</p><p><strong>Arguments</strong></p><ul><li><p><code>dir::AbstractString</code>: The directory in which the files will be generated. Note that this will be joined to <code>pkg_name</code>.</p></li><li><p><code>pkg_name::AbstractString</code>: Name of the package.</p></li><li><p><code>template::Template</code>: The template whose tests we are generating.</p></li></ul><p>Returns an array of generated file/directory names.</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL186-L202">source</a><br/></section><h4><a class="nav-anchor" id="gen_require-1" href="#gen_require-1"><code>gen_require</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.gen_require" href="#PkgTemplates.gen_require"><code>PkgTemplates.gen_require</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">gen_require(
|
|
dir::AbstractString,
|
|
pkg_name::AbstractString,
|
|
template::Template,
|
|
) -> Vector{String}</code></pre><p>Create the <code>REQUIRE</code> file in the temp package directory.</p><p><strong>Arguments</strong></p><ul><li><p><code>dir::AbstractString</code>: The directory in which the files will be generated. Note that this will be joined to <code>pkg_name</code>.</p></li><li><p><code>pkg_name::AbstractString</code>: Name of the package.</p></li><li><p><code>template::Template</code>: The template whose REQUIRE we are generating.</p></li></ul><p>Returns an array of generated file/directory names.</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL216-L232">source</a><br/></section><h4><a class="nav-anchor" id="gen_readme-1" href="#gen_readme-1"><code>gen_readme</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.gen_readme" href="#PkgTemplates.gen_readme"><code>PkgTemplates.gen_readme</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">gen_readme(
|
|
dir::AbstractString,
|
|
pkg_name::AbstractString,
|
|
template::Template,
|
|
) -> Vector{String}</code></pre><p>Create a README in the temp package directory with badges for each enabled plugin.</p><p><strong>Arguments</strong></p><ul><li><p><code>dir::AbstractString</code>: The directory in which the files will be generated. Note that this will be joined to <code>pkg_name</code>.</p></li><li><p><code>pkg_name::AbstractString</code>: Name of the package.</p></li><li><p><code>template::Template</code>: The template whose README we are generating.</p></li></ul><p>Returns an array of generated file/directory names.</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL241-L257">source</a><br/></section><h4><a class="nav-anchor" id="gen_gitignore-1" href="#gen_gitignore-1">gen_gitignore</a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.gen_gitignore" href="#PkgTemplates.gen_gitignore"><code>PkgTemplates.gen_gitignore</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">gen_gitignore(
|
|
dir::AbstractString,
|
|
pkg_name::AbstractString,
|
|
template::Template,
|
|
) -> Vector{String}</code></pre><p>Create a <code>.gitignore</code> in the temp package directory.</p><p><strong>Arguments</strong></p><ul><li><p><code>dir::AbstractString</code>: The directory in which the files will be generated. Note that this will be joined to <code>pkg_name</code>.</p></li><li><p><code>pkg_name::AbstractString</code>: Name of the package.</p></li><li><p><code>template::Template</code>: The template whose .gitignore we are generating.</p></li></ul><p>Returns an array of generated file/directory names.</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL284-L300">source</a><br/></section><h4><a class="nav-anchor" id="gen_license-1" href="#gen_license-1">gen_license</a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.gen_license" href="#PkgTemplates.gen_license"><code>PkgTemplates.gen_license</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">gen_license(
|
|
dir::AbstractString,
|
|
pkg_name::AbstractString,
|
|
template::Template,
|
|
) -> Vector{String}</code></pre><p>Create a license in the temp package directory.</p><p><strong>Arguments</strong></p><ul><li><p><code>dir::AbstractString</code>: The directory in which the files will be generated. Note that this will be joined to <code>pkg_name</code>.</p></li><li><p><code>pkg_name::AbstractString</code>: Name of the package.</p></li><li><p><code>template::Template</code>: The template whose LICENSE we are generating.</p></li></ul><p>Returns an array of generated file/directory names.</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL315-L331">source</a><br/></section><footer><hr/><a class="previous" href="../index.html"><span class="direction">Previous</span><span class="title">Home</span></a><a class="next" href="plugins.html"><span class="direction">Next</span><span class="title">Plugins</span></a></footer></article></body></html>
|