-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathindex.html
1564 lines (1445 loc) · 117 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.2, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Bazel rules for Emacs Lisp</title>
<meta name="description" content="Bazel rules for Emacs Lisp">
<meta name="keywords" content="Bazel rules for Emacs Lisp">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="#Top" rel="start" title="Top">
<link href="#Indices" rel="index" title="Indices">
<link href="#SEC_Contents" rel="contents" title="Table of Contents">
<link href="#Introduction" rel="next" title="Introduction">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
a.summary-letter-printindex {text-decoration: none}
div.example {margin-left: 3.2em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
td.printindex-index-entry {vertical-align: top}
td.printindex-index-section {vertical-align: top; padding-left: 1em}
th.entries-header-printindex {text-align:left}
th.sections-header-printindex {text-align:left; padding-left: 1em}
ul.mark-bullet {list-style-type: disc}
ul.toc-numbered-mark {list-style: none}
-->
</style>
</head>
<body lang="en">
<div class="top-level-extent" id="Top">
<div class="nav-panel">
<p>
Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h1 class="top" id="Bazel-rules-for-Emacs-Lisp"><span>Bazel rules for Emacs Lisp<a class="copiable-link" href="#Bazel-rules-for-Emacs-Lisp"> ¶</a></span></h1>
<div class="region-contents" id="SEC_Contents">
<h2 class="contents-heading">Table of Contents</h2>
<div class="contents">
<ul class="toc-numbered-mark">
<li><a id="toc-Introduction" href="#Introduction">1 Introduction</a></li>
<li><a id="toc-Requirements" href="#Requirements">2 Requirements</a></li>
<li><a id="toc-Usage" href="#Usage">3 Usage</a></li>
<li><a id="toc-Load-path-management" href="#Load-path-management">4 Load path management</a></li>
<li><a id="toc-Runfiles" href="#Runfiles">5 Runfiles</a></li>
<li><a id="toc-Protocol-buffers" href="#Protocol-buffers">6 Protocol buffers</a>
<ul class="toc-numbered-mark">
<li><a id="toc-Accessing-protocol-buffer-message-fields" href="#Protocol-buffer-fields">6.1 Accessing protocol buffer message fields</a></li>
<li><a id="toc-Parsing-and-serializing-protocol-buffer-messages" href="#Protocol-buffer-serialization">6.2 Parsing and serializing protocol buffer messages</a></li>
<li><a id="toc-Well_002dknown-protocol-buffer-types" href="#Well_002dknown-protocol-buffer-types">6.3 Well-known protocol buffer types</a></li>
<li><a id="toc-Specialized-array-and-map-functions" href="#Protocol-buffer-array-and-map-functions">6.4 Specialized array and map functions</a></li>
</ul></li>
<li><a id="toc-Building-manuals" href="#Building-manuals">7 Building manuals</a></li>
<li><a id="toc-Depending-on-external-libraries" href="#Depending-on-external-libraries">8 Depending on external libraries</a></li>
<li><a id="toc-Starlark-infrastructure" href="#Starlark-infrastructure">9 Starlark infrastructure</a></li>
<li><a id="toc-Indices" href="#Indices">10 Indices</a>
<ul class="toc-numbered-mark">
<li><a id="toc-Concept-index" href="#Concept-index" rel="index">10.1 Concept index</a></li>
<li><a id="toc-Symbol-index" href="#Symbol-index" rel="index">10.2 Symbol index</a></li>
<li><a id="toc-Type-index" href="#Type-index" rel="index">10.3 Type index</a></li>
</ul></li>
</ul>
</div>
</div>
<hr>
<div class="chapter-level-extent" id="Introduction">
<div class="nav-panel">
<p>
Next: <a href="#Requirements" accesskey="n" rel="next">Requirements</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Bazel rules for Emacs Lisp</a>, Up: <a href="#Top" accesskey="u" rel="up">Bazel rules for Emacs Lisp</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Introduction-1"><span>1 Introduction<a class="copiable-link" href="#Introduction-1"> ¶</a></span></h2>
<p>This repository provides a Bazel integration for Emacs Lisp; see
<a class="uref" href="https://bazel.build/">the Bazel homepage</a> for more information about Bazel,
and see <a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Top">the Emacs Lisp manual</a>. It is modeled after the
rules definitions for other languages, like the
<a class="uref" href="https://bazel.build/reference/be/c-cpp">C++ rules</a>.
</p>
<p>This is not an officially supported Google product.
</p>
<hr>
</div>
<div class="chapter-level-extent" id="Requirements">
<div class="nav-panel">
<p>
Next: <a href="#Usage" accesskey="n" rel="next">Usage</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Bazel rules for Emacs Lisp</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Requirements-1"><span>2 Requirements<a class="copiable-link" href="#Requirements-1"> ¶</a></span></h2>
<p>To use <code class="code">rules_elisp</code>, you need <a class="uref" href="https://bazel.build/">Bazel</a>. For
installation instructions, see <a class="uref" href="https://bazel.build/install">Installing
Bazel</a>. This repository supports all full Bazel releases starting with Bazel
7.2.1. You’ll also need a recent C/C++ compiler (GCC or Clang on GNU/Linux and
macOS, Visual C++ 2019 on Windows) and at least Python 3.12. For further
instructions how to use Bazel on Windows, see
<a class="uref" href="https://bazel.build/install/windows">Installing Bazel on Windows</a>.
</p>
<p>This repository generally supports the two most recent major versions of Emacs.
Currently, the supported versions are Emacs 29 and Emacs 30. Once Emacs 31 is
released, support for Emacs 29 will be dropped.
</p>
<hr>
</div>
<div class="chapter-level-extent" id="Usage">
<div class="nav-panel">
<p>
Next: <a href="#Load-path-management" accesskey="n" rel="next">Load path management</a>, Previous: <a href="#Requirements" accesskey="p" rel="prev">Requirements</a>, Up: <a href="#Top" accesskey="u" rel="up">Bazel rules for Emacs Lisp</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Usage-1"><span>3 Usage<a class="copiable-link" href="#Usage-1"> ¶</a></span></h2>
<p>Add a snippet like the following to your <code class="code">MODULE.bazel</code> file:
</p>
<div class="example">
<pre class="example-preformatted">bazel_dep(name = "phst_rules_elisp")
git_override(
module_name = "phst_rules_elisp",
remote = "https://github.com/phst/rules_elisp.git",
commit = "10054ee512b7087eb53d92f4f85857b778e53357",
)
</pre></div>
<p>See <a class="uref" href="https://bazel.build/external/overview#bzlmod">the Bzlmod documentation</a>
for background information. Then you can use the <code class="code">elisp_library</code>,
<code class="code">elisp_cc_module</code>, <code class="code">elisp_binary</code>, and <code class="code">elisp_test</code> rules. See the rule
documentation below and the examples in the <code class="code">examples</code> directory for details.
Note that the C++ code used by <code class="code">rules_elisp</code> requires at least C++17, but Bazel
still compiles with C++11 by default. See
<a class="uref" href="https://github.com/abseil/abseil-cpp/blob/master/FAQ.md#how-to-i-set-the-c-dialect-used-to-build-abseil">the
Abseil FAQ</a> how to correctly change the C++ standard for your project.
</p>
<dl class="first-deffn def-block">
<dt class="deffn def-line" id="index-elisp_005flibrary"><span class="category-def">Rule: </span><span><strong class="def-name">elisp_library</strong> <var class="def-var-arguments">(name, [fatal_warnings], srcs, [outs], [data], [load_path], [deps])</var><a class="copiable-link" href="#index-elisp_005flibrary"> ¶</a></span></dt>
<dd>
<div class="example">
<pre class="example-preformatted">load("@phst_rules_elisp//elisp:elisp_library.bzl", "elisp_library")
</pre></div>
<p>Byte-compiles Emacs Lisp source files and makes the compiled output
available to dependencies. All sources are byte-compiled.
<code class="code">elisp_library</code>, <code class="code">elisp_binary</code>, and <code class="code">elisp_test</code> rules depending on this binary
can then use <code class="code">load</code> or <code class="code">require</code> to load them.
</p>
<p>By default, libraries need to be loaded using a filename relative to the
repository root, i.e., <var class="var">package</var>/<var class="var">file</var>. If you want to add
further elements to the load path, use the <code class="code">load_path</code> attribute.
</p>
<p>If there are multiple source files specified in <code class="code">srcs</code>, these source files can
also load each other. However, it’s often preferable to only have one
<code class="code">elisp_library</code> target per source file to make dependencies more obvious and
ensure that files get only loaded in their byte-compiled form.
</p>
<p>The source files in <code class="code">srcs</code> can also list shared objects. The rule treats them
as Emacs modules and doesn’t try to byte-compile them. You can use
e.g. <code class="code">cc_binary</code> with <code class="code">linkshared = True</code> to create shared objects.
</p>
<p>The <code class="code">elisp_library</code> rule supports the following attributes:
</p>
<dl class="table">
<dt><code class="code">name</code></dt>
<dd><p>A unique name for this target. Name; mandatory.
</p></dd>
<dt><code class="code">fatal_warnings</code></dt>
<dd><p>If <code class="code">True</code> (the default), then byte compile warnings should
be treated as errors. If <code class="code">False</code>, they still show up in the output, but don’t
cause the compilation to fail. Most targets should leave this attribute as
<code class="code">True</code>, because otherwise important issues might remain undetected. Set this
attribute to <code class="code">False</code> only for integrating third-party libraries that don’t
compile cleanly and that you don’t control. Boolean; optional; default:
<code class="code">True</code>.
</p></dd>
<dt><code class="code">srcs</code></dt>
<dd><p>List of source files. These must either be Emacs Lisp files ending
in <code class="code">.el</code>, or module objects ending in <code class="code">.so</code>, <code class="code">.dylib</code>, or <code class="code">.dll</code>. List of
labels; mandatory.
</p></dd>
<dt><code class="code">outs</code></dt>
<dd><p>List of byte-compiled Emacs Lisp files to be made available as
targets. List of output files; optional; default: <code class="code">[]</code>.
</p></dd>
<dt><code class="code">data</code></dt>
<dd><p>List of files to be made available at runtime. List of labels;
optional; default: <code class="code">[]</code>.
</p></dd>
<dt><code class="code">load_path</code></dt>
<dd><p>List of additional load path elements. The elements are
directory names, which can be either relative or absolute. Relative names are
relative to the current package. Absolute names are relative to the
repository root. To add a load path entry for the current package, specify
<code class="code">.</code> here. List of strings; optional; default: <code class="code">[]</code>.
</p></dd>
<dt><code class="code">deps</code></dt>
<dd><p>List of <code class="code">elisp_library</code> dependencies. List of labels; optional;
default: <code class="code">[]</code>; required providers: <code class="code">EmacsLispInfo</code>.
</p></dd>
</dl>
</dd></dl>
<dl class="first-deffn def-block">
<dt class="deffn def-line" id="index-elisp_005fcc_005fmodule"><span class="category-def">Rule: </span><span><strong class="def-name">elisp_cc_module</strong> <var class="def-var-arguments">(name, [srcs], [deps], [data], [copts], [linkopts], [local_defines])</var><a class="copiable-link" href="#index-elisp_005fcc_005fmodule"> ¶</a></span></dt>
<dd>
<div class="example">
<pre class="example-preformatted">load("@phst_rules_elisp//elisp:elisp_cc_module.bzl", "elisp_cc_module")
</pre></div>
<p>Builds an Emacs dynamic module from C and C++ source files.
For background on Emacs modules, see
<a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Dynamic-Modules">Emacs Dynamic Modules</a>, and see
<a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Writing-Dynamic-Modules">Writing Dynamically-Loaded Modules</a>.
The <code class="code">emacs_module</code> rule is similar to
<a class="uref" href="https://bazel.build/reference/be/c-cpp#cc_library"><code class="code">cc_library</code></a>,
but it always builds a dynamic library (shared object) that can be loaded
into Emacs. The module can also be used directly as dependency
for <code class="code">elisp_library</code>, <code class="code">elisp_binary</code>, and <code class="code">elisp_test</code> rules.
The dynamic library will only export the symbols necessary for Emacs modules,
<code class="code">plugin_is_GPL_compatible</code> and <code class="code">emacs_module_init</code>; see
<a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Module-Initialization">Module Initialization Code</a>.
The file name of the dynamic library will be
<code class="code"><var class="var">name</var>.<var class="var">extension</var></code>, where <var class="var">name</var>
is the rule name as specified in the <code class="code">name</code> attribute, and <var class="var">extension</var>
is the correct extension for dynamic libraries for the target operating system.
The file name will not be prefixed with <code class="code">lib</code>.
</p>
<p>The library code in <code class="code">srcs</code> can include a recent version of <code class="code">emacs-module.h</code>
using
</p><div class="example">
<pre class="example-preformatted">#include "emacs-module.h"
</pre></div>
<p>to implement module functions.
</p>
<p>The <code class="code">elisp_cc_module</code> rule supports the following attributes:
</p>
<dl class="table">
<dt><code class="code">name</code></dt>
<dd><p>A unique name for this target. Name; mandatory.
</p></dd>
<dt><code class="code">srcs</code></dt>
<dd><p>C and C++ source files for the module. See the
<a class="uref" href="https://bazel.build/reference/be/c-cpp#cc_library.srcs">corresponding
attribute for <code class="code">cc_library</code></a>. List of labels; optional; default: <code class="code">[]</code>.
</p></dd>
<dt><code class="code">deps</code></dt>
<dd><p><code class="code">cc_library</code> targets that the module depends on. See the
<a class="uref" href="https://bazel.build/reference/be/c-cpp#cc_library.deps">corresponding
attribute for <code class="code">cc_library</code></a>. List of labels; optional; default: <code class="code">[]</code>;
required providers: <code class="code">CcInfo</code>.
</p></dd>
<dt><code class="code">data</code></dt>
<dd><p>Data dependencies to make available at runtime. See the
<a class="uref" href="https://bazel.build/reference/be/c-cpp#cc_library.data">corresponding
attribute for <code class="code">cc_library</code></a>. List of labels; optional; default: <code class="code">[]</code>.
</p></dd>
<dt><code class="code">copts</code></dt>
<dd><p>Additional options to pass to the C/C++ compiler. See the
<a class="uref" href="https://bazel.build/reference/be/c-cpp#cc_library.copts">corresponding
attribute for <code class="code">cc_library</code></a>. List of strings; optional; default: <code class="code">[]</code>.
</p></dd>
<dt><code class="code">linkopts</code></dt>
<dd><p>Additional options to pass to the C/C++ linker. See the
<a class="uref" href="https://bazel.build/reference/be/c-cpp#cc_library.linkopts">corresponding
attribute for <code class="code">cc_library</code></a>. List of strings; optional; default: <code class="code">[]</code>.
</p></dd>
<dt><code class="code">local_defines</code></dt>
<dd><p>Additional preprocessor definitions to pass to the C/C++
compiler. See the
<a class="uref" href="https://bazel.build/reference/be/c-cpp#cc_library.local_defines">corresponding
attribute for <code class="code">cc_library</code></a>. List of strings; optional; default: <code class="code">[]</code>.
</p></dd>
</dl>
</dd></dl>
<dl class="first-deffn def-block">
<dt class="deffn def-line" id="index-elisp_005fbinary"><span class="category-def">Rule: </span><span><strong class="def-name">elisp_binary</strong> <var class="def-var-arguments">(name, [fatal_warnings], src, [data], [deps], [interactive], [input_args], [output_args])</var><a class="copiable-link" href="#index-elisp_005fbinary"> ¶</a></span></dt>
<dd>
<div class="example">
<pre class="example-preformatted">load("@phst_rules_elisp//elisp:elisp_binary.bzl", "elisp_binary")
</pre></div>
<p>Binary rule that loads a single Emacs Lisp file.
The source file is byte-compiled. At runtime, the compiled version is loaded
in batch mode unless <code class="code">interactive</code> is <code class="code">True</code>.
</p>
<p>The <code class="code">elisp_binary</code> rule supports the following attributes:
</p>
<dl class="table">
<dt><code class="code">name</code></dt>
<dd><p>A unique name for this target. Name; mandatory.
</p></dd>
<dt><code class="code">fatal_warnings</code></dt>
<dd><p>If <code class="code">True</code> (the default), then byte compile warnings should
be treated as errors. If <code class="code">False</code>, they still show up in the output, but don’t
cause the compilation to fail. Most targets should leave this attribute as
<code class="code">True</code>, because otherwise important issues might remain undetected. Set this
attribute to <code class="code">False</code> only for integrating third-party libraries that don’t
compile cleanly and that you don’t control. Boolean; optional; default:
<code class="code">True</code>.
</p></dd>
<dt><code class="code">src</code></dt>
<dd><p>Source file to load. Label; mandatory.
</p></dd>
<dt><code class="code">data</code></dt>
<dd><p>List of files to be made available at runtime. List of labels;
optional; default: <code class="code">[]</code>.
</p></dd>
<dt><code class="code">deps</code></dt>
<dd><p>List of <code class="code">elisp_library</code> dependencies. List of labels; optional;
default: <code class="code">[]</code>; required providers: <code class="code">EmacsLispInfo</code>.
</p></dd>
<dt><code class="code">interactive</code></dt>
<dd><p>Run Emacs in interactive instead of batch mode. Boolean;
optional; default: <code class="code">False</code>.
</p></dd>
<dt><code class="code">input_args</code></dt>
<dd><p>Indices of command-line arguments that represent input
filenames. These numbers specify indices into the <code class="code">argv</code> array. Negative
indices are interpreted as counting from the end of the array. For example,
the index <code class="code">2</code> stands for <code class="code">argv[2]</code>, and the index <code class="code">-2</code> stands for <code class="code">argv[argc -
2]</code>. When passing arguments to an <code class="code">emacs_binary</code> program on the command line,
the corresponding arguments are treated as filenames for input files and added
to the <code class="code">inputFiles</code> field of the manifest. This only has an effect for
toolchains that specify <code class="code">wrap = True</code>. List of integers; optional; default:
<code class="code">[]</code>.
</p></dd>
<dt><code class="code">output_args</code></dt>
<dd><p>Indices of command-line arguments that represent output
filenames. These numbers specify indices into the <code class="code">argv</code> array. Negative
indices are interpreted as counting from the end of the array. For example,
the index <code class="code">2</code> stands for <code class="code">argv[2]</code>, and the index <code class="code">-2</code> stands for <code class="code">argv[argc -
2]</code>. When passing arguments to an <code class="code">emacs_binary</code> program on the command line,
the corresponding arguments are treated as filenames for output files and
added to the <code class="code">outputFiles</code> field of the manifest. This only has an effect for
toolchains that specify <code class="code">wrap = True</code>. List of integers; optional; default:
<code class="code">[]</code>.
</p></dd>
</dl>
</dd></dl>
<dl class="first-deffn def-block">
<dt class="deffn def-line" id="index-elisp_005ftest"><span class="category-def">Rule: </span><span><strong class="def-name">elisp_test</strong> <var class="def-var-arguments">(name, [fatal_warnings], srcs, [data], [deps], [skip_tests], [skip_tags])</var><a class="copiable-link" href="#index-elisp_005ftest"> ¶</a></span></dt>
<dd>
<div class="example">
<pre class="example-preformatted">load("@phst_rules_elisp//elisp:elisp_test.bzl", "elisp_test")
</pre></div>
<p>Runs ERT tests that are defined in the source files.
The given source files should contain ERT tests defined with <code class="code">ert-deftest</code>.
For details, see <a data-manual="ert" href="https://www.gnu.org/software/emacs/manual/html_mono/ert.html#How-to-Write-Tests">How to Write Tests</a>.
The generated test binary loads all source files and executes all
tests like <code class="code">ert-run-tests-batch-and-exit</code>.
</p>
<p>You can restrict the tests to be run using the <code class="code">--test_filter</code> option. If set,
the value of <code class="code">--test_filter</code> must be a Lisp expression usable as an
ERT test selector; see <a data-manual="ert" href="https://www.gnu.org/software/emacs/manual/html_mono/ert.html#Test-Selectors">Test Selectors</a>.
You can also restrict the tests to be run using the <code class="code">skip_tests</code> and
<code class="code">skip_tags</code> rule attributes. These restrictions are additive, i.e., a test
only runs if it’s not suppressed by either facility.
</p>
<p>In coverage mode (i.e., when run under <code class="code">bazel coverage</code>), all tests tagged with
the <code class="code">:nocover</code> tag are also skipped. You can use this tag to skip tests that
normally pass, but don’t work under coverage for some reason.
</p>
<p>Test files can access additional command-line arguments passed via the <code class="code">args</code>
attribute or the <code class="code">--test_arg</code> Bazel option via the <code class="code">command-line-args-left</code>
variable. After processing known arguments, test files must remove them from
<code class="code">command-line-args-left</code> so that it’s empty after all test files are loaded.
Emacs will not automatically process these arguments using
<code class="code">command-switch-alist</code> or <code class="code">command-line-functions</code>.
</p>
<p>The <code class="code">elisp_test</code> rule supports the following attributes:
</p>
<dl class="table">
<dt><code class="code">name</code></dt>
<dd><p>A unique name for this target. Name; mandatory.
</p></dd>
<dt><code class="code">fatal_warnings</code></dt>
<dd><p>If <code class="code">True</code> (the default), then byte compile warnings should
be treated as errors. If <code class="code">False</code>, they still show up in the output, but don’t
cause the compilation to fail. Most targets should leave this attribute as
<code class="code">True</code>, because otherwise important issues might remain undetected. Set this
attribute to <code class="code">False</code> only for integrating third-party libraries that don’t
compile cleanly and that you don’t control. Boolean; optional; default:
<code class="code">True</code>.
</p></dd>
<dt><code class="code">srcs</code></dt>
<dd><p>List of source files to load. List of labels; mandatory.
</p></dd>
<dt><code class="code">data</code></dt>
<dd><p>List of files to be made available at runtime. List of labels;
optional; default: <code class="code">[]</code>.
</p></dd>
<dt><code class="code">deps</code></dt>
<dd><p>List of <code class="code">elisp_library</code> dependencies. List of labels; optional;
default: <code class="code">[]</code>; required providers: <code class="code">EmacsLispInfo</code>.
</p></dd>
<dt><code class="code">skip_tests</code></dt>
<dd><p>List of tests to skip. This attribute contains a list of ERT
test symbols; when running the test rule, these tests are skipped. Most of
the time, you should use the <code class="code">skip-unless</code> macro instead; see <a data-manual="ert" href="https://www.gnu.org/software/emacs/manual/html_mono/ert.html#Tests-and-Their-Environment">Tests and Their Environment</a>. The <code class="code">skip_tests</code>
attribute is mainly useful for third-party code that you don’t control. List
of strings; optional; default: <code class="code">[]</code>.
</p></dd>
<dt><code class="code">skip_tags</code></dt>
<dd><p>List of test tags to skip. This attribute contains a list of
tag names; if a test is tagged with one of the tags from this list, it is
skipped. This can be useful to e.g. skip tests that are flaky or only work
in interactive mode. Use the <code class="code">:tags</code> keyword argument to <code class="code">ert-deftest</code> to tag
tests. List of strings; optional; default: <code class="code">[]</code>.
</p></dd>
</dl>
</dd></dl>
<hr>
</div>
<div class="chapter-level-extent" id="Load-path-management">
<div class="nav-panel">
<p>
Next: <a href="#Runfiles" accesskey="n" rel="next">Runfiles</a>, Previous: <a href="#Usage" accesskey="p" rel="prev">Usage</a>, Up: <a href="#Top" accesskey="u" rel="up">Bazel rules for Emacs Lisp</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Load-path-management-1"><span>4 Load path management<a class="copiable-link" href="#Load-path-management-1"> ¶</a></span></h2>
<a class="index-entry-id" id="index-Load-path"></a>
<p>The Emacs Lisp rules by default only add the repository root directories to the
load path; see <a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Library-Search">(elisp)Library Search</a>. However, many Emacs Lisp
libraries assume that their immediate parent directory is present in the load
path. To support such libraries, the <code class="code">elisp_library</code> rule supports an optional
<code class="code">load_path</code> attribute. You can specify additional load path directories using
this attribute. Relative directories are relative to the Bazel package
directory; absolute directories are relative to the repository root. A typical
use case is to specify <code class="code">load_path = ["."]</code> to add the current package to the
load path.
</p>
<hr>
</div>
<div class="chapter-level-extent" id="Runfiles">
<div class="nav-panel">
<p>
Next: <a href="#Protocol-buffers" accesskey="n" rel="next">Protocol buffers</a>, Previous: <a href="#Load-path-management" accesskey="p" rel="prev">Load path management</a>, Up: <a href="#Top" accesskey="u" rel="up">Bazel rules for Emacs Lisp</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Runfiles-1"><span>5 Runfiles<a class="copiable-link" href="#Runfiles-1"> ¶</a></span></h2>
<a class="index-entry-id" id="index-Runfiles"></a>
<p>This repository also includes a library to access runfiles; see
<a class="uref" href="https://bazel.build/extending/rules#runfiles">the Bazel documentation on
runfiles</a>. To use it, add a build dependency on
<code class="code">@phst_rules_elisp//elisp/runfiles</code>.
</p>
<a class="index-entry-id" id="index-elisp_002frunfiles_002frlocation"></a>
<a class="index-entry-id" id="index-elisp_002frunfiles_002frunfiles"></a>
<p>Use the function <code class="code">elisp/runfiles/rlocation</code> to map a runfile name to a
filename in the local filesystem. For more advanced use cases, see the
class <code class="code">elisp/runfiles/runfiles</code>.
</p>
<a class="index-entry-id" id="index-elisp_002frunfiles_002ffile_002dhandler"></a>
<p>The library also provides a file name handler for runfiles,
<code class="code">elisp/runfiles/file-handler</code>. It uses the prefix ‘<samp class="samp">/bazel-runfile:</samp>’.
</p>
<hr>
</div>
<div class="chapter-level-extent" id="Protocol-buffers">
<div class="nav-panel">
<p>
Next: <a href="#Building-manuals" accesskey="n" rel="next">Building manuals</a>, Previous: <a href="#Runfiles" accesskey="p" rel="prev">Runfiles</a>, Up: <a href="#Top" accesskey="u" rel="up">Bazel rules for Emacs Lisp</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Protocol-buffers-1"><span>6 Protocol buffers<a class="copiable-link" href="#Protocol-buffers-1"> ¶</a></span></h2>
<a class="index-entry-id" id="index-Protocol-buffers"></a>
<p>By defining <code class="code">elisp_proto_library</code> rules, you can use protocol buffers in Emacs
Lisp; see <a class="uref" href="https://developers.google.com/protocol-buffers">https://developers.google.com/protocol-buffers</a>. To make a
protocol buffer definition available to Emacs Lisp, you first need a
<code class="code">proto_library</code> rule; see
<a class="uref" href="https://bazel.build/reference/be/protocol-buffer#proto_library">https://bazel.build/reference/be/protocol-buffer#proto_library</a>. You can
either use an existing <code class="code">proto_library</code> rule or add your own. Then, add an
<code class="code">elisp_proto_library</code> rule that references the <code class="code">proto_library</code> rule. Normally,
the name of the <code class="code">proto_library</code> rule ends in ‘<samp class="samp">_proto</samp>’, and the name of the
corresponding <code class="code">elisp_proto_library</code> rule has the same prefix and ends in
‘<samp class="samp">_elisp_proto</samp>’. For example:
</p>
<div class="example">
<pre class="example-preformatted">load("@phst_rules_elisp//elisp/proto:elisp_proto_library.bzl", "elisp_proto_library")
load("@protobuf//bazel:proto_library.bzl", "proto_library")
proto_library(
name = "my_proto",
srcs = ["my.proto"],
)
elisp_proto_library(
name = "my_elisp_proto",
deps = [":my_proto"],
)
</pre></div>
<p>You can then use the <code class="code">elisp_proto_library</code> rule in the same way as a normal
<code class="code">elisp_library</code> rule, i.e., depend on it in other <code class="code">elisp_library</code>,
<code class="code">elisp_binary</code>, or <code class="code">elisp_test</code> rules. The name of the Emacs Lisp feature for
the library is the same as the name of the original ‘<samp class="samp">.proto</samp>’ file, relative to
its repository root. For example, if the above BUILD file is in a package named
‘<samp class="samp">mypackage</samp>’, you would load the protocol buffer library using <code class="code">(require
'mypackage/my.proto)</code>.
</p>
<dl class="first-deffn def-block">
<dt class="deffn def-line" id="index-elisp_005fproto_005flibrary"><span class="category-def">Rule: </span><span><strong class="def-name">elisp_proto_library</strong> <var class="def-var-arguments">(name, deps)</var><a class="copiable-link" href="#index-elisp_005fproto_005flibrary"> ¶</a></span></dt>
<dd>
<div class="example">
<pre class="example-preformatted">load("@phst_rules_elisp//elisp/proto:elisp_proto_library.bzl", "elisp_proto_library")
</pre></div>
<p>Generates Emacs bindings for a protocol buffer library.
By convention, for a <code class="code">proto_library</code> rule named
<code class="code"><var class="var">prefix</var>_proto</code> there should be a corresponding
<code class="code">elisp_proto_library</code> rule named <code class="code"><var class="var">prefix</var>_elisp_proto</code>.
Other <code class="code">elisp_library</code>, <code class="code">elisp_binary</code>, and <code class="code">elisp_test</code> rules can then depend
on this rule. This rule generates and byte-compiles Emacs Lisp representations
of the protocol buffer definitions listed in the <code class="code">deps</code> attribute and all their
direct and indirect dependencies. The feature symbol for <code class="code">require</code> is the
filename of the original <code class="code">.proto</code> file listed in the <code class="code">proto_library</code> rule,
relative to its repository root.
</p>
<p>The <code class="code">elisp_proto_library</code> rule supports the following attributes:
</p>
<dl class="table">
<dt><code class="code">name</code></dt>
<dd><p>A unique name for this target. Name; mandatory.
</p></dd>
<dt><code class="code">deps</code></dt>
<dd><p>List of exactly one <code class="code">proto_library</code> rule. List of labels;
mandatory; required providers: <code class="code">ProtoInfo</code>.
</p></dd>
</dl>
</dd></dl>
<p>Emacs Lisp protocol buffer bindings contain Emacs Lisp equivalents for all
message and enumeration types defined in the underlying protocol buffer
definition files. Because Emacs Lisp doesn’t have namespaces, the names of all
defined entities are the full names of the corresponding protocol buffer
descriptors, including the protocol buffer package name (which is often
different from the Bazel package name), but with dots (‘<samp class="samp">.</samp>’) replaced with
slashes (‘<samp class="samp">/</samp>’), because dots are special characters in Emacs Lisp; see
<a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Symbol-Type">(elisp)Symbol Type</a>. For example, the Lisp name of the protocol buffer
message type <code class="code">google.protobuf.Duration</code> is <code class="code">google/protobuf/Duration</code>, and the
Lisp name of the protocol buffer enumeration value
<code class="code">google.protobuf.FieldDescriptorProto.TYPE_BOOL</code> is
<code class="code">google/protobuf/FieldDescriptorProto/TYPE_BOOL</code>.
</p>
<p>When accessing protocol buffer message fields, Emacs translates field values to
and from Lisp data types; see <a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Programming-Types">(elisp)Programming Types</a>. For scalar
types, the translation uses appropriate matching types, i.e., numbers and
strings. Boolean values are translated to either <code class="code">nil</code> or <code class="code">t</code>. The <code class="code">bytes</code>
type is represented using unibyte strings; see <a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Text-Representations">(elisp)Text Representations</a>. Accessing string and byte fields always creates copies; this
means that changing the return value using <code class="code">aset</code> will not modify the original
protocol buffer message.
</p>
<p>The situation is a bit more complex for submessage fields, repeated fields, and
map fields. Emacs represents values of these fields using specialized types.
For submessage fields, these types are again generated protocol buffer message
types. For repeated and map fields, Emacs uses the types <code class="code">elisp/proto/array</code>
and <code class="code">elisp/proto/map</code>, respectively. Message, array, and map objects can be
mutable or immutable; attempting to modify an immutable object signals an error.
The Lisp representations of these types are opaque structure-like types. Their
implementation is maintained internally, and you shouldn’t try to access or
modify it directly. Rather, the Emacs Lisp library <code class="code">elisp/proto/proto</code> contains
the following facilities to use and manipulate these types.
</p>
<dl class="first-deftp def-block">
<dt class="deftp def-line" id="index-elisp_002fproto_002fmessage"><span class="category-def">Type: </span><span><strong class="def-name">elisp/proto/message</strong><a class="copiable-link" href="#index-elisp_002fproto_002fmessage"> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-protocol-buffer-message"></a>
<p>The base type for all message types. This is an abstract type; you can’t
instantiate it directly.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fmessage_002dp"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/message-p</strong> <var class="def-var-arguments">object</var><a class="copiable-link" href="#index-elisp_002fproto_002fmessage_002dp"> ¶</a></span></dt>
<dd><p>This predicate returns whether the given object is a protocol buffer message
object.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fmessage_002dmutable_002dp"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/message-mutable-p</strong> <var class="def-var-arguments">object</var><a class="copiable-link" href="#index-elisp_002fproto_002fmessage_002dmutable_002dp"> ¶</a></span></dt>
<dd><p>This predicate returns whether the given protocol buffer message object is
mutable.
</p></dd></dl>
<dl class="first-deftp def-block">
<dt class="deftp def-line" id="index-elisp_002fproto_002farray"><span class="category-def">Type: </span><span><strong class="def-name">elisp/proto/array</strong><a class="copiable-link" href="#index-elisp_002fproto_002farray"> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-protocol-buffer-array"></a>
<p>A type that represents repeated protocol buffer message fields. You can’t
instantiate this type directly; instead, you obtain instances of this type by
accessing repeated message fields.
</p>
<p>Protocol buffer arrays are generalized sequences. This means you can use the
functions from the <code class="code">seq.el</code> library with them. See <a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Sequence-Functions">(elisp)Sequence Functions</a>.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002farray_002dp"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/array-p</strong> <var class="def-var-arguments">object</var><a class="copiable-link" href="#index-elisp_002fproto_002farray_002dp"> ¶</a></span></dt>
<dd><p>This predicate returns whether the given object is a protocol buffer array
object.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002farray_002dmutable_002dp"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/array-mutable-p</strong> <var class="def-var-arguments">object</var><a class="copiable-link" href="#index-elisp_002fproto_002farray_002dmutable_002dp"> ¶</a></span></dt>
<dd><p>This predicate returns whether the given protocol buffer array is mutable.
</p></dd></dl>
<dl class="first-deftp def-block">
<dt class="deftp def-line" id="index-elisp_002fproto_002fmap"><span class="category-def">Type: </span><span><strong class="def-name">elisp/proto/map</strong><a class="copiable-link" href="#index-elisp_002fproto_002fmap"> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-protocol-buffer-map"></a>
<p>A type that represents protocol buffer map fields. You can’t instantiate this
type directly; instead, you obtain instances of this type by accessing repeated
message fields. See
<a class="uref" href="https://developers.google.com/protocol-buffers/docs/proto3#maps">https://developers.google.com/protocol-buffers/docs/proto3#maps</a>.
</p>
<p>Protocol buffer maps are generalized maps. This means you can use the functions
from the <code class="code">map.el</code> library with them. See the comments in <code class="code">map.el</code> for details.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fmap_002dp"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/map-p</strong> <var class="def-var-arguments">object</var><a class="copiable-link" href="#index-elisp_002fproto_002fmap_002dp"> ¶</a></span></dt>
<dd><p>This predicate returns whether the given object is a protocol buffer map object.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fmap_002dmutable_002dp"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/map-mutable-p</strong> <var class="def-var-arguments">object</var><a class="copiable-link" href="#index-elisp_002fproto_002fmap_002dmutable_002dp"> ¶</a></span></dt>
<dd><p>This predicate returns whether the given protocol buffer map is mutable.
</p></dd></dl>
<p>It should be noted that protocol buffer arrays and maps are not “full” types.
You can’t use them as replacement types for vectors or hash tables because
there’s no way to create objects of these types from scratch. You can only
obtain new objects by accessing protocol buffer message fields. This is also
the reason why these types don’t provide implementations of <code class="code">seq-into</code>,
<code class="code">seq-concatenate</code> or <code class="code">map-into</code> that would return new protocol buffer arrays and
maps.
</p>
<p>Another important difference between these types and the standard Emacs Lisp
types is that protocol buffer arrays and maps are strongly-typed: all their
elements have the same type, which is determined when creating the object. For
example, you can’t add a string value to a protocol buffer array holding
integers.
</p>
<p>The Lisp representation of protocol buffer enumerations are plain Lisp
constants. See <a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Defining-Variables">(elisp)Defining Variables</a>. Their values are just the
integral values of the corresponding enumerators.
</p>
<p>Whenever Emacs needs to convert a Lisp value to a protocol buffer field value,
an array element, or a map key or value, it accepts values that are compatible
with the destination type. For example, you can use an integer to set a
floating-point protocol buffer message field. Setting a Boolean field accepts
any non-<code class="code">nil</code> value as <code class="code">true</code>. Setting a repeated field accepts lists, vectors,
and any other generalized sequence type. Setting a map field accepts
hash-tables, association lists, and any other generalized map type.
</p>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fmake"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/make</strong> <var class="def-var-arguments">type [fields...]</var><a class="copiable-link" href="#index-elisp_002fproto_002fmake"> ¶</a></span></dt>
<dd><p>This function creates and initializes a new protocol buffer message object. The
<var class="var">type</var> must be a symbol denoting an existing protocol buffer message
type, using the conventions described above (i.e., periods replaced with
slashes). Before calling this function for a given type, you have to <code class="code">require</code>
the generated library that defines the type, otherwise the function will fail.
The <var class="var">fields</var> are keyword-value pairs of the form
<code class="code">:<var class="var">field</var> <var class="var">value</var></code> that are used to initialize the
fields. If a field isn’t mentioned in <var class="var">fields</var>, it’s not set in the
resulting message. For example, the following code creates a new protocol
buffer message object of type <code class="code">google.protobuf.Duration</code>:
</p>
<div class="example lisp">
<pre class="lisp-preformatted">(require 'elisp/proto/proto)
(require 'duration_proto)
(elisp/proto/make 'google/protobuf/Duration :seconds 3600)
</pre></div>
<p>The <code class="code">nanos</code> field remains uninitialized.
</p></dd></dl>
<p>For every protocol buffer message type, the generated library will also contain
a function <code class="code"><var class="var">type</var>-new</code> that you can use as a shorthand for
<code class="code">elisp/proto/make</code>. For example, you could also write the above example as
</p>
<div class="example lisp">
<pre class="lisp-preformatted">(require 'duration_proto)
(google/protobuf/Duration-new :seconds 3600)
</pre></div>
<p>To check whether an object is a protocol buffer message object of a given type,
the generated libraries contain predicate functions like
<code class="code"><var class="var">type</var>-p</code>. For example, to test whether an object is a
duration protocol buffer message, you can write
</p>
<div class="example lisp">
<pre class="lisp-preformatted">(require 'duration_proto)
(google/protobuf/Duration-p object)
</pre></div>
<p>You can also use the Common Lisp type predicates like <code class="code">cl-typep</code> or
<code class="code">cl-check-type</code> with protocol buffer message objects. See
<a data-manual="cl" href="https://www.gnu.org/software/emacs/manual/html_mono/cl.html#Type-Predicates">(cl)Type Predicates</a>.
</p>
<ul class="mini-toc">
<li><a href="#Protocol-buffer-fields" accesskey="1">Accessing protocol buffer message fields</a></li>
<li><a href="#Protocol-buffer-serialization" accesskey="2">Parsing and serializing protocol buffer messages</a></li>
<li><a href="#Well_002dknown-protocol-buffer-types" accesskey="3">Well-known protocol buffer types</a></li>
<li><a href="#Protocol-buffer-array-and-map-functions" accesskey="4">Specialized array and map functions</a></li>
</ul>
<hr>
<div class="section-level-extent" id="Protocol-buffer-fields">
<div class="nav-panel">
<p>
Next: <a href="#Protocol-buffer-serialization" accesskey="n" rel="next">Parsing and serializing protocol buffer messages</a>, Up: <a href="#Protocol-buffers" accesskey="u" rel="up">Protocol buffers</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Accessing-protocol-buffer-message-fields"><span>6.1 Accessing protocol buffer message fields<a class="copiable-link" href="#Accessing-protocol-buffer-message-fields"> ¶</a></span></h3>
<p>The functions described in this section retrieve and manipulate message fields.
They all accept a message object as first argument and a field name as second
argument. The field name is a plain symbol denoting the unqualified field name.
</p>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fhas_002dfield"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/has-field</strong> <var class="def-var-arguments">message field</var><a class="copiable-link" href="#index-elisp_002fproto_002fhas_002dfield"> ¶</a></span></dt>
<dd><p>This function returns whether the given field is present in the message object.
If the field doesn’t have a notion of presence (e.g., it’s a repeated field), an
error is signaled.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002ffield"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/field</strong> <var class="def-var-arguments">message field</var><a class="copiable-link" href="#index-elisp_002fproto_002ffield"> ¶</a></span></dt>
<dd><p>This function returns the value of the given field within the message object.
If the field isn’t set in the message, then the return value depends on the type
of the field. If the field is scalar, its default value is returned. If the
field is a submessage, repeated, or map field, <code class="code">nil</code> is returned. For
non-scalar fields, the return value is immutable, i.e., trying to change it will
signal an error.
</p>
<p>If the field is a string or byte array field, the return value is a
newly-allocated string. This implies that it’s often a good idea to bind the
return value to a local variable instead of retrieving the value many times.
</p></dd></dl>
<dl class="first-deffn def-block">
<dt class="deffn def-line" id="index-elisp_002fproto"><span class="category-def">pcase pattern: </span><span><strong class="def-name">elisp/proto</strong> <var class="def-var-arguments">type [fields...]</var><a class="copiable-link" href="#index-elisp_002fproto"> ¶</a></span></dt>
<dd><p>As a more compact alternative to type predicates and field access using
<code class="code">elisp/proto/field</code>, you can use <code class="code">elisp/proto</code> patterns in <code class="code">pcase</code> form. See
<a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Pattern_002dMatching-Conditional">(elisp)Pattern-Matching Conditional</a>. The <code class="code">elisp/proto</code> form takes an
unquoted protocol buffer type and a list of fields. For example, the following
form extracts the fields of a duration message:
</p>
<div class="example lisp">
<pre class="lisp-preformatted">(pcase message
((elisp/proto google/protobuf/Duration seconds nanos)
(message "Duration with %d seconds and %d nanoseconds"
seconds nanos))
(_ (message "Some other thing")))
</pre></div>
<p>Instead of specifying plain field names, you can also specify
<code class="code">(<var class="var">field</var> <var class="var">pattern</var>)</code> pairs. These match the field
value against <var class="var">pattern</var>, which is again a <code class="code">pcase</code> pattern. For
example, the following code tests whether a duration is strictly positive:
</p>
<div class="example lisp">
<pre class="lisp-preformatted">(pcase message
((or (elisp/proto google/protobuf/Duration
(seconds (and (pred cl-plusp) seconds))
nanos)
(elisp/proto google/protobuf/Duration
(seconds (and 0 seconds))
(nanos (and (pred cl-plusp) nanos))))
(message "Duration with %d seconds and %d nanoseconds is positive"
seconds nanos)))
</pre></div>
<p>A <var class="var">field</var> construct that is a plain symbol is thus the same as
<code class="code">(<var class="var">field</var> <var class="var">field</var>)</code>.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fset_002dfield"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/set-field</strong> <var class="def-var-arguments">message field value</var><a class="copiable-link" href="#index-elisp_002fproto_002fset_002dfield"> ¶</a></span></dt>
<dd><p>This function sets the field to a new value. It signals an error if the message
object is immutable, or if the new value isn’t compatible with the field type.
</p></dd></dl>
<hr>
</div>
<div class="section-level-extent" id="Protocol-buffer-serialization">
<div class="nav-panel">
<p>
Next: <a href="#Well_002dknown-protocol-buffer-types" accesskey="n" rel="next">Well-known protocol buffer types</a>, Previous: <a href="#Protocol-buffer-fields" accesskey="p" rel="prev">Accessing protocol buffer message fields</a>, Up: <a href="#Protocol-buffers" accesskey="u" rel="up">Protocol buffers</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Parsing-and-serializing-protocol-buffer-messages"><span>6.2 Parsing and serializing protocol buffer messages<a class="copiable-link" href="#Parsing-and-serializing-protocol-buffer-messages"> ¶</a></span></h3>
<p>The primary purpose of protocol buffers is data serialization. The Emacs Lisp
protocol buffer bindings support all three major forms of protocol buffer
serialization: binary, JSON, and text. However, currently the textual protocol
buffer representation can only be generated, not parsed. Since none of the
serialized forms are self-describing, you have to explicitly pass the desired
message type to the parsing functions.
</p>
<p>You can customize the behavior of the parsing and serialization functions to
some extend with optional keyword arguments. These are the most common keyword
arguments:
</p>
<dl class="table">
<dt><code class="code">:allow-partial</code></dt>
<dd><p>This keyword argument affects how missing required fields
are handled: by default, they cause an error to be signaled, but if the
keyword argument is non-<code class="code">nil</code>, they are silently ignored, and the result might
not be fully initialized.
</p></dd>
<dt><code class="code">:discard-unknown</code></dt>
<dd><p>This keyword argument affects how unknown fields are
handled: by default, they cause an error to be signaled, but if the keyword
argument is non-<code class="code">nil</code>, they are silently ignored.
</p></dd>
<dt><code class="code">:deterministic</code></dt>
<dd><p>If this keyword argument is non-<code class="code">nil</code>, serialization
functions attempt to produce slightly more deterministic output; however, this
attempt is best-effort, since protocol buffer serialization is not guaranteed
to be deterministic.
</p></dd>
</dl>
<p>Other keyword arguments are described in the main body of the function
definitions below.
</p>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fparse"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/parse</strong> <var class="def-var-arguments">type serialized [:allow-partial]</var><a class="copiable-link" href="#index-elisp_002fproto_002fparse"> ¶</a></span></dt>
<dd><p>This function parses a protocol buffer message from its binary serialization
form. The <var class="var">serialized</var> argument must be a unibyte string containing
the binary serialization of a protocol buffer message of type <var class="var">type</var>.
The <var class="var">type</var> is again a symbol denoting a protocol buffer message type.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fparse_002djson"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/parse-json</strong> <var class="def-var-arguments">type serialized [:discard-unknown]</var><a class="copiable-link" href="#index-elisp_002fproto_002fparse_002djson"> ¶</a></span></dt>
<dd><p>This function is like <code class="code">elisp/proto/parse</code>, but it expects the JSON serialization
instead of the binary serialization.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fserialize"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/serialize</strong> <var class="def-var-arguments">message [:allow-partial] [:discard-unknown] [:deterministic]</var><a class="copiable-link" href="#index-elisp_002fproto_002fserialize"> ¶</a></span></dt>
<dd><p>This function is the inverse of <code class="code">elisp/proto/parse</code>, producing the binary
serialization of the <var class="var">message</var> as a unibyte string.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fserialize_002dtext"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/serialize-text</strong> <var class="def-var-arguments">message [:compact] [:discard-unknown] [:deterministic]</var><a class="copiable-link" href="#index-elisp_002fproto_002fserialize_002dtext"> ¶</a></span></dt>
<dd><p>This function is the inverse of <code class="code">elisp/proto/parse</code>, producing the binary
serialization of the <var class="var">message</var> as a unibyte string. If the
<code class="code">:compact</code> keyword argument is non-<code class="code">nil</code>, the output is a bit more compact, with
less vertical whitespace; however, you shouldn’t rely on any specific output
format in any case.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fserialize_002djson"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/serialize-json</strong> <var class="def-var-arguments">message [:emit-defaults] [:proto-names]</var><a class="copiable-link" href="#index-elisp_002fproto_002fserialize_002djson"> ¶</a></span></dt>
<dd><p>This function is the inverse of <code class="code">elisp/proto/parse-json</code>, producing the JSON
serialization of the <var class="var">message</var> as a string. If the <code class="code">:emit-defaults</code>
keyword argument is non-<code class="code">nil</code>, the result will also include fields whose value
equals their default value; normally such fields are left out. The
<code class="code">:proto-names</code> keyword argument determines the naming style for field names: by
default, camel-case versions of the names are used, but if the keyword argument
is non-<code class="code">nil</code>, the names from the protocol buffer definition are used verbatim.
</p></dd></dl>
<p>You can print a human-readable representation of protocol buffer messages,
arrays, and maps using the functions <code class="code">cl-prin1</code>, <code class="code">cl-prin1-to-string</code>, or
<code class="code">cl-print-to-string-with-limit</code>. However, these objects don’t have a read
syntax; see <a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Printed-Representation">(elisp)Printed Representation</a>. Using plain Emacs functions
like <code class="code">print</code> will result in a representation that’s not very human-readable; see
<a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Read-and-Print">(elisp)Read and Print</a>.
</p>
<hr>
</div>
<div class="section-level-extent" id="Well_002dknown-protocol-buffer-types">
<div class="nav-panel">
<p>
Next: <a href="#Protocol-buffer-array-and-map-functions" accesskey="n" rel="next">Specialized array and map functions</a>, Previous: <a href="#Protocol-buffer-serialization" accesskey="p" rel="prev">Parsing and serializing protocol buffer messages</a>, Up: <a href="#Protocol-buffers" accesskey="u" rel="up">Protocol buffers</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Well_002dknown-protocol-buffer-types-1"><span>6.3 Well-known protocol buffer types<a class="copiable-link" href="#Well_002dknown-protocol-buffer-types-1"> ¶</a></span></h3>
<p>The Emacs Lisp protocol buffer bindings contain some dedicated support for a few
well-known message types. These are predefined types which are used frequently;
see
<a class="uref" href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf">https://developers.google.com/protocol-buffers/docs/reference/google.protobuf</a>.
</p>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002ftimestamp"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/timestamp</strong> <var class="def-var-arguments">message</var><a class="copiable-link" href="#index-elisp_002fproto_002ftimestamp"> ¶</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn def-line" id="index-elisp_002fproto_002fduration"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/duration</strong> <var class="def-var-arguments">message</var><a class="copiable-link" href="#index-elisp_002fproto_002fduration"> ¶</a></span></dt>
<dd><p>These functions convert protocol buffer messages of type
<code class="code">google.protobuf.Timestamp</code> and <code class="code">google.protobuf.Duration</code> to Lisp timestamps.
See <a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Time-of-Day">(elisp)Time of Day</a>, for the definition of a Lisp timestamp.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fmake_002dtimestamp"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/make-timestamp</strong> <var class="def-var-arguments">time</var><a class="copiable-link" href="#index-elisp_002fproto_002fmake_002dtimestamp"> ¶</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn def-line" id="index-elisp_002fproto_002fmake_002dduration"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/make-duration</strong> <var class="def-var-arguments">time</var><a class="copiable-link" href="#index-elisp_002fproto_002fmake_002dduration"> ¶</a></span></dt>
<dd><p>These functions perform the opposite conversion, creating
<code class="code">google.protobuf.Timestamp</code> and <code class="code">google.protobuf.Duration</code> messages from Lisp
time values. See <a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Time-of-Day">(elisp)Time of Day</a>, for the definition of a Lisp time
value.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fset_002dtimestamp"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/set-timestamp</strong> <var class="def-var-arguments">message time</var><a class="copiable-link" href="#index-elisp_002fproto_002fset_002dtimestamp"> ¶</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn def-line" id="index-elisp_002fproto_002fset_002dduration"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/set-duration</strong> <var class="def-var-arguments">message time</var><a class="copiable-link" href="#index-elisp_002fproto_002fset_002dduration"> ¶</a></span></dt>
<dd><p>These functions are similar, but they change message objects in place instead of
creating new ones. The <var class="var">message</var> arguments must be mutable. As an
alternative to calling these functions directly, you can also use
<code class="code">elisp/proto/timestamp</code> and <code class="code">elisp/proto/duration</code> as generalized variables; see
<a data-manual="elisp" href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Generalized-Variables">(elisp)Generalized Variables</a>.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fpack_002dany"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/pack-any</strong> <var class="def-var-arguments">message</var><a class="copiable-link" href="#index-elisp_002fproto_002fpack_002dany"> ¶</a></span></dt>
<dd><p>This function returns a new protocol buffer message of type
<code class="code">google.protobuf.Any</code> that wraps the given <var class="var">message</var>.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002funpack_002dany"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/unpack-any</strong> <var class="def-var-arguments">any</var><a class="copiable-link" href="#index-elisp_002fproto_002funpack_002dany"> ¶</a></span></dt>
<dd><p>This function unpacks the given protocol buffer message of type
<code class="code">google.protobuf.Any</code>. The return type depends on the <code class="code">type_url</code> field. Even
though this allows you to handle message types dynamically, you still need to
load the generated bindings for the dynamic type for unpacking to work.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fany_002dtype_002dname"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/any-type-name</strong> <var class="def-var-arguments">any</var><a class="copiable-link" href="#index-elisp_002fproto_002fany_002dtype_002dname"> ¶</a></span></dt>
<dd><p>This function extracts the full type name from the <code class="code">type_url</code> field of the given
protocol buffer message of type <code class="code">google.protobuf.Any</code>. The return name is the
full name of the type of the message packed in <var class="var">any</var> as a string.
</p></dd></dl>
<hr>
</div>
<div class="section-level-extent" id="Protocol-buffer-array-and-map-functions">
<div class="nav-panel">
<p>
Previous: <a href="#Well_002dknown-protocol-buffer-types" accesskey="p" rel="prev">Well-known protocol buffer types</a>, Up: <a href="#Protocol-buffers" accesskey="u" rel="up">Protocol buffers</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Specialized-array-and-map-functions"><span>6.4 Specialized array and map functions<a class="copiable-link" href="#Specialized-array-and-map-functions"> ¶</a></span></h3>
<p>This section describes a few additional functions that deal with arrays and
maps.
</p>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002farray_002dlength"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/array-length</strong> <var class="def-var-arguments">array</var><a class="copiable-link" href="#index-elisp_002fproto_002farray_002dlength"> ¶</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn def-line" id="index-elisp_002fproto_002fmap_002dlength"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/map-length</strong> <var class="def-var-arguments">map</var><a class="copiable-link" href="#index-elisp_002fproto_002fmap_002dlength"> ¶</a></span></dt>
<dd><p>These functions return the number of elements in the given array or map.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fdo_002darray"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/do-array</strong> <var class="def-var-arguments">function array</var><a class="copiable-link" href="#index-elisp_002fproto_002fdo_002darray"> ¶</a></span></dt>
<dd><p>This function calls <var class="var">function</var> for each element in <var class="var">array</var> in
ascending order. <var class="var">function</var> has to accept a single argument.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fdo_002dmap"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/do-map</strong> <var class="def-var-arguments">function map</var><a class="copiable-link" href="#index-elisp_002fproto_002fdo_002dmap"> ¶</a></span></dt>
<dd><p>This function calls <var class="var">function</var> for each entry in <var class="var">map</var>.
<var class="var">function</var> has to accept two arguments, the key and the value. The
iteration order is arbitrary.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fappend_002darray"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/append-array</strong> <var class="def-var-arguments">array value</var><a class="copiable-link" href="#index-elisp_002fproto_002fappend_002darray"> ¶</a></span></dt>
<dd><p>This function adds <var class="var">value</var> as a new element to the end of
<var class="var">array</var>.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fextend_002darray"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/extend-array</strong> <var class="def-var-arguments">dest source</var><a class="copiable-link" href="#index-elisp_002fproto_002fextend_002darray"> ¶</a></span></dt>
<dd><p>This function appends all elements in the <var class="var">source</var> sequence to the end
of <var class="var">dest</var>. The <var class="var">source</var> must be a generalized sequence.
</p></dd></dl>
<dl class="first-deffn first-defun-alias-first-deffn def-block">
<dt class="deffn defun-alias-deffn def-line" id="index-elisp_002fproto_002fupdate_002dmap"><span class="category-def">Function: </span><span><strong class="def-name">elisp/proto/update-map</strong> <var class="def-var-arguments">dest source</var><a class="copiable-link" href="#index-elisp_002fproto_002fupdate_002dmap"> ¶</a></span></dt>
<dd><p>This function inserts all entries in the <var class="var">source</var> map into
<var class="var">map</var>. The <var class="var">source</var> must be a generalized map. If a given