223 lines
8.2 KiB
Plaintext
Generated
223 lines
8.2 KiB
Plaintext
Generated
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>Go by Example: Embed Directive</title>
|
|
<link rel=stylesheet href="site.css">
|
|
</head>
|
|
<script>
|
|
onkeydown = (e) => {
|
|
|
|
if (e.key == "ArrowLeft") {
|
|
window.location.href = 'struct-embedding';
|
|
}
|
|
|
|
|
|
if (e.key == "ArrowRight") {
|
|
window.location.href = 'generics';
|
|
}
|
|
|
|
}
|
|
</script>
|
|
<body>
|
|
<div class="example" id="embed-directive">
|
|
<h2><a href="./">Go by Example</a>: Embed Directive</h2>
|
|
|
|
<table>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
<p>Starting in Go version 1.16+, Go supports use of <code>//go:embed</code>
|
|
which is a directive to embed files and folders into
|
|
the application binary by the compiler.</p>
|
|
|
|
</td>
|
|
<td class="code empty leading">
|
|
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
<p>Since Go does not have preprocessor or macros like C type of languages,
|
|
<code>pragmas/directives</code> are implemented by the compiler as comments <code>//</code>.
|
|
Using <code>//go:embed</code> tells the compiler to include arbitrary files/folders in binary.</p>
|
|
|
|
</td>
|
|
<td class="code leading">
|
|
<a href="http://play.golang.org/p/gk3Zh5Sx8rV"><img title="Run code" src="play.png" class="run" /></a><img title="Copy code" src="clipboard.png" class="copy" />
|
|
<pre class="chroma">
|
|
<span class="kn">package</span> <span class="nx">main</span>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
<p>If you are not using any exported identifiers from <code>embed</code> package directly,
|
|
you can add an underscore <code>_</code> before the package name, ask Go to import <code>embed</code>
|
|
without directly using it, like this: <code>_ "embed"</code>. In this example, we remove the
|
|
underscore as we need to use the <code>embed.FS</code> type from the package.</p>
|
|
|
|
</td>
|
|
<td class="code leading">
|
|
|
|
<pre class="chroma">
|
|
<span class="kn">import</span> <span class="p">(</span>
|
|
<span class="s">"embed"</span>
|
|
<span class="p">)</span>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
<p>Since one file is defined after the directive, the compiler will only include
|
|
this single file, followed by variable <code>single_file_string</code> to access as <code>string</code> type.</p>
|
|
|
|
</td>
|
|
<td class="code leading">
|
|
|
|
<pre class="chroma">
|
|
<span class="c1">//go:embed embed-directive.sh
|
|
</span><span class="c1"></span><span class="kd">var</span> <span class="nx">single_file_string</span> <span class="kt">string</span>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
<p>Here is a similar example but include single file as <code>[]byte</code>.
|
|
Note that <code>//go:embed</code> can only be used in package level,
|
|
define it in any function will result in error.</p>
|
|
|
|
</td>
|
|
<td class="code leading">
|
|
|
|
<pre class="chroma">
|
|
<span class="c1">//go:embed embed-directive.sh
|
|
</span><span class="c1"></span><span class="kd">var</span> <span class="nx">single_file_byte</span> <span class="p">[]</span><span class="kt">byte</span>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
<p>We can also embed multiple files or even folders with wildcard.
|
|
Since Go resolves these files and folders during compile time, we have to use the files in
|
|
current working directory as examples. In practice, you can embed files with <code>"//go:embed /path/to/folder"</code>
|
|
or with another example <code>"//go:embed /path/to/folder/*"</code>. You can add multiple <code>//go:embed</code> before defining a variable.</p>
|
|
|
|
</td>
|
|
<td class="code leading">
|
|
|
|
<pre class="chroma">
|
|
<span class="c1">//go:embed *.hash
|
|
</span><span class="c1">//go:embed embed-directive.sh
|
|
</span><span class="c1"></span><span class="kd">var</span> <span class="nx">folder_FS</span> <span class="nx">embed</span><span class="p">.</span><span class="nx">FS</span>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
|
|
</td>
|
|
<td class="code leading">
|
|
|
|
<pre class="chroma"><span class="kd">func</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
<p>Print out the content of <code>embed-directive.sh</code> as <code>string</code>.</p>
|
|
|
|
</td>
|
|
<td class="code leading">
|
|
|
|
<pre class="chroma">
|
|
<span class="nb">println</span><span class="p">(</span><span class="nx">single_file_string</span><span class="p">)</span>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
<p>Print out the content of <code>embed-directive.sh</code> as <code>[]byte</code>.</p>
|
|
|
|
</td>
|
|
<td class="code leading">
|
|
|
|
<pre class="chroma">
|
|
<span class="nb">println</span><span class="p">(</span><span class="nb">string</span><span class="p">(</span><span class="nx">single_file_byte</span><span class="p">))</span>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
<p>Print out the content of <code>embed-directive.hash</code> by reading the file from <code>folder_FS</code> first,
|
|
then print out the content.</p>
|
|
|
|
</td>
|
|
<td class="code leading">
|
|
|
|
<pre class="chroma">
|
|
<span class="nx">hash_file</span> <span class="o">:=</span> <span class="s">"embed-directive.hash"</span>
|
|
<span class="nx">hash_content</span><span class="p">,</span> <span class="nx">_</span> <span class="o">:=</span> <span class="nx">folder_FS</span><span class="p">.</span><span class="nf">ReadFile</span><span class="p">(</span><span class="nx">hash_file</span><span class="p">)</span>
|
|
<span class="nb">println</span><span class="p">(</span><span class="nb">string</span><span class="p">(</span><span class="nx">hash_content</span><span class="p">))</span>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
|
|
</td>
|
|
<td class="code">
|
|
|
|
<pre class="chroma"><span class="p">}</span>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
|
|
<tr>
|
|
<td class="docs">
|
|
<p>Use these commands to run the example</p>
|
|
|
|
</td>
|
|
<td class="code">
|
|
|
|
<pre class="chroma">
|
|
<span class="gp">$</span> go run embed-directive.go</pre>
|
|
</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
<p class="next">
|
|
Next example: <a href="generics">Generics</a>.
|
|
</p>
|
|
|
|
|
|
<p class="footer">
|
|
by <a href="https://markmcgranaghan.com">Mark McGranaghan</a> and <a href="https://eli.thegreenplace.net">Eli Bendersky</a> | <a href="https://github.com/mmcgrana/gobyexample">source</a> | <a href="https://github.com/mmcgrana/gobyexample#license">license</a>
|
|
</p>
|
|
|
|
</div>
|
|
<script>
|
|
var codeLines = [];
|
|
codeLines.push('');codeLines.push('package main\u000A');codeLines.push('import (\u000A \"embed\"\u000A)\u000A');codeLines.push('//go:embed embed-directive.sh\u000Avar single_file_string string\u000A');codeLines.push('//go:embed embed-directive.sh\u000Avar single_file_byte []byte\u000A');codeLines.push('//go:embed *.hash\u000A//go:embed embed-directive.sh\u000Avar folder_FS embed.FS\u000A');codeLines.push('func main() {\u000A');codeLines.push(' println(single_file_string)\u000A');codeLines.push(' println(string(single_file_byte))\u000A');codeLines.push(' hash_file :\u003D \"embed-directive.hash\"\u000A hash_content, _ :\u003D folder_FS.ReadFile(hash_file)\u000A println(string(hash_content))\u000A');codeLines.push('}\u000A');codeLines.push('');
|
|
</script>
|
|
<script src="site.js" async></script>
|
|
</body>
|
|
</html>
|