unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
blob 09a3973d6489e29df176436e79f042d9075d6cd2 41272 bytes (raw)
name: doc/lispref/compile.texi 	 # note: path name is non-authoritative(*)

   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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
 
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990--1994, 2001--2021 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Byte Compilation
@chapter Byte Compilation
@cindex byte compilation
@cindex byte-code
@cindex compilation (Emacs Lisp)

  Emacs Lisp has a @dfn{compiler} that translates functions written
in Lisp into a special representation called @dfn{byte-code} that can be
executed more efficiently.  The compiler replaces Lisp function
definitions with byte-code.  When a byte-code function is called, its
definition is evaluated by the @dfn{byte-code interpreter}.

  Because the byte-compiled code is evaluated by the byte-code
interpreter, instead of being executed directly by the machine's
hardware (as true compiled code is), byte-code is completely
transportable from machine to machine without recompilation.  It is not,
however, as fast as true compiled code.

  In general, any version of Emacs can run byte-compiled code produced
by recent earlier versions of Emacs, but the reverse is not true.

@vindex no-byte-compile
  If you do not want a Lisp file to be compiled, ever, put a file-local
variable binding for @code{no-byte-compile} into it, like this:

@example
;; -*-no-byte-compile: t; -*-
@end example

@menu
* Speed of Byte-Code::          An example of speedup from byte compilation.
* Compilation Functions::       Byte compilation functions.
* Docs and Compilation::        Dynamic loading of documentation strings.
* Dynamic Loading::             Dynamic loading of individual functions.
* Eval During Compile::         Code to be evaluated when you compile.
* Compiler Errors::             Handling compiler error messages.
* Byte-Code Objects::           The data type used for byte-compiled functions.
* Disassembly::                 Disassembling byte-code; how to read byte-code.
@end menu

@node Speed of Byte-Code
@section Performance of Byte-Compiled Code

  A byte-compiled function is not as efficient as a primitive function
written in C, but runs much faster than the version written in Lisp.
Here is an example:

@example
@group
(defun silly-loop (n)
  "Return the time, in seconds, to run N iterations of a loop."
  (let ((t1 (float-time)))
    (while (> (setq n (1- n)) 0))
    (- (float-time) t1)))
@result{} silly-loop
@end group

@group
(silly-loop 50000000)
@result{} 10.235304117202759
@end group

@group
(byte-compile 'silly-loop)
@result{} @r{[Compiled code not shown]}
@end group

@group
(silly-loop 50000000)
@result{} 3.705854892730713
@end group
@end example

  In this example, the interpreted code required 10 seconds to run,
whereas the byte-compiled code required less than 4 seconds.  These
results are representative, but actual results may vary.

@node Compilation Functions
@section Byte-Compilation Functions
@cindex compilation functions

  You can byte-compile an individual function or macro definition with
the @code{byte-compile} function.  You can compile a whole file with
@code{byte-compile-file}, or several files with
@code{byte-recompile-directory} or @code{batch-byte-compile}.

@vindex byte-compile-debug
  Sometimes, the byte compiler produces warning and/or error messages
(@pxref{Compiler Errors}, for details).  These messages are normally
recorded in a buffer called @file{*Compile-Log*}, which uses
Compilation mode.  @xref{Compilation Mode,,,emacs, The GNU Emacs
Manual}.  However, if the variable @code{byte-compile-debug} is
non-@code{nil}, error messages will be signaled as Lisp errors instead
(@pxref{Errors}).

@cindex macro compilation
  Be careful when writing macro calls in files that you intend to
byte-compile.  Since macro calls are expanded when they are compiled,
the macros need to be loaded into Emacs or the byte compiler will not
do the right thing.  The usual way to handle this is with
@code{require} forms which specify the files containing the needed
macro definitions (@pxref{Named Features}).  Normally, the
byte compiler does not evaluate the code that it is compiling, but it
handles @code{require} forms specially, by loading the specified
libraries.  To avoid loading the macro definition files when someone
@emph{runs} the compiled program, write @code{eval-when-compile}
around the @code{require} calls (@pxref{Eval During Compile}).  For
more details, @xref{Compiling Macros}.

  Inline (@code{defsubst}) functions are less troublesome; if you
compile a call to such a function before its definition is known, the
call will still work right, it will just run slower.

@defun byte-compile symbol
This function byte-compiles the function definition of @var{symbol},
replacing the previous definition with the compiled one.  The function
definition of @var{symbol} must be the actual code for the function;
@code{byte-compile} does not handle function indirection.  The return
value is the byte-code function object which is the compiled
definition of @var{symbol} (@pxref{Byte-Code Objects}).

@example
@group
(defun factorial (integer)
  "Compute factorial of INTEGER."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
@result{} factorial
@end group

@group
(byte-compile 'factorial)
@result{}
#[(integer)
  "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
  [integer 1 * factorial]
  4 "Compute factorial of INTEGER."]
@end group
@end example

If @var{symbol}'s definition is a byte-code function object,
@code{byte-compile} does nothing and returns @code{nil}.  It does not
compile the symbol's definition again, since the original
(non-compiled) code has already been replaced in the symbol's function
cell by the byte-compiled code.

The argument to @code{byte-compile} can also be a @code{lambda}
expression.  In that case, the function returns the corresponding
compiled code but does not store it anywhere.
@end defun

@deffn Command compile-defun &optional arg
This command reads the defun containing point, compiles it, and
evaluates the result.  If you use this on a defun that is actually a
function definition, the effect is to install a compiled version of that
function.

@code{compile-defun} normally displays the result of evaluation in the
echo area, but if @var{arg} is non-@code{nil}, it inserts the result
in the current buffer after the form it has compiled.
@end deffn

@deffn Command byte-compile-file filename
This function compiles a file of Lisp code named @var{filename} into a
file of byte-code.  The output file's name is made by changing the
@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in
@samp{.el}, it adds @samp{.elc} to the end of @var{filename}.

Compilation works by reading the input file one form at a time.  If it
is a definition of a function or macro, the compiled function or macro
definition is written out.  Other forms are batched together, then each
batch is compiled, and written so that its compiled code will be
executed when the file is read.  All comments are discarded when the
input file is read.

This command returns @code{t} if there were no errors and @code{nil}
otherwise.  When called interactively, it prompts for the file name.

@example
@group
$ ls -l push*
-rw-r--r-- 1 lewis lewis 791 Oct  5 20:31 push.el
@end group

@group
(byte-compile-file "~/emacs/push.el")
     @result{} t
@end group

@group
$ ls -l push*
-rw-r--r-- 1 lewis lewis 791 Oct  5 20:31 push.el
-rw-rw-rw- 1 lewis lewis 638 Oct  8 20:25 push.elc
@end group
@end example
@end deffn

@deffn Command byte-recompile-directory directory &optional flag force follow-symlinks
@cindex library compilation
This command recompiles every @samp{.el} file in @var{directory} (or
its subdirectories) that needs recompilation.  A file needs
recompilation if a @samp{.elc} file exists but is older than the
@samp{.el} file.

When a @samp{.el} file has no corresponding @samp{.elc} file,
@var{flag} says what to do.  If it is @code{nil}, this command ignores
these files.  If @var{flag} is 0, it compiles them.  If it is neither
@code{nil} nor 0, it asks the user whether to compile each such file,
and asks about each subdirectory as well.

Interactively, @code{byte-recompile-directory} prompts for
@var{directory} and @var{flag} is the prefix argument.

If @var{force} is non-@code{nil}, this command recompiles every
@samp{.el} file that has a @samp{.elc} file.

This command will normally not compile @samp{.el} files that are
symlinked.  If the optional @var{follow-symlink} parameter is
non-@code{nil}, symlinked @samp{.el} will also be compiled.

The returned value is unpredictable.
@end deffn

@defun batch-byte-compile &optional noforce
This function runs @code{byte-compile-file} on files specified on the
command line.  This function must be used only in a batch execution of
Emacs, as it kills Emacs on completion.  An error in one file does not
prevent processing of subsequent files, but no output file will be
generated for it, and the Emacs process will terminate with a nonzero
status code.

If @var{noforce} is non-@code{nil}, this function does not recompile
files that have an up-to-date @samp{.elc} file.

@example
$ emacs -batch -f batch-byte-compile *.el
@end example
@end defun

@node Docs and Compilation
@section Documentation Strings and Compilation
@cindex dynamic loading of documentation

  When Emacs loads functions and variables from a byte-compiled file,
it normally does not load their documentation strings into memory.
Each documentation string is dynamically loaded from the
byte-compiled file only when needed.  This saves memory, and speeds up
loading by skipping the processing of the documentation strings.

  This feature has a drawback: if you delete, move, or alter the
compiled file (such as by compiling a new version), Emacs may no
longer be able to access the documentation string of previously-loaded
functions or variables.  Such a problem normally only occurs if you
build Emacs yourself, and happen to edit and/or recompile the Lisp
source files.  To solve it, just reload each file after recompilation.

  Dynamic loading of documentation strings from byte-compiled files is
determined, at compile time, for each byte-compiled file.  It can be
disabled via the option @code{byte-compile-dynamic-docstrings}.

@defopt byte-compile-dynamic-docstrings
If this is non-@code{nil}, the byte compiler generates compiled files
that are set up for dynamic loading of documentation strings.

To disable the dynamic loading feature for a specific file, set this
option to @code{nil} in its header line (@pxref{File Variables, ,
Local Variables in Files, emacs, The GNU Emacs Manual}), like this:

@smallexample
-*-byte-compile-dynamic-docstrings: nil;-*-
@end smallexample

This is useful mainly if you expect to change the file, and you want
Emacs sessions that have already loaded it to keep working when the
file changes.
@end defopt

@cindex @samp{#@@@var{count}}
@cindex @samp{#$}
Internally, the dynamic loading of documentation strings is
accomplished by writing compiled files with a special Lisp reader
construct, @samp{#@@@var{count}}.  This construct skips the next
@var{count} characters.  It also uses the @samp{#$} construct, which
stands for the name of this file, as a string.  Do not use these
constructs in Lisp source files; they are not designed to be clear to
humans reading the file.

@node Dynamic Loading
@section Dynamic Loading of Individual Functions

@cindex dynamic loading of functions
@cindex lazy loading
  When you compile a file, you can optionally enable the @dfn{dynamic
function loading} feature (also known as @dfn{lazy loading}).  With
dynamic function loading, loading the file doesn't fully read the
function definitions in the file.  Instead, each function definition
contains a place-holder which refers to the file.  The first time each
function is called, it reads the full definition from the file, to
replace the place-holder.

  The advantage of dynamic function loading is that loading the file
should become faster.  This is a good thing for a file which contains
many separate user-callable functions, if using one of them does not
imply you will probably also use the rest.  A specialized mode which
provides many keyboard commands often has that usage pattern: a user may
invoke the mode, but use only a few of the commands it provides.

  The dynamic loading feature has certain disadvantages:

@itemize @bullet
@item
If you delete or move the compiled file after loading it, Emacs can no
longer load the remaining function definitions not already loaded.

@item
If you alter the compiled file (such as by compiling a new version),
then trying to load any function not already loaded will usually yield
nonsense results.
@end itemize

  These problems will never happen in normal circumstances with
installed Emacs files.  But they are quite likely to happen with Lisp
files that you are changing.  The easiest way to prevent these problems
is to reload the new compiled file immediately after each recompilation.

  @emph{Experience shows that using dynamic function loading provides
benefits that are hardly measurable, so this feature is deprecated
since Emacs 27.1.}

  The byte compiler uses the dynamic function loading feature if the
variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
time.  Do not set this variable globally, since dynamic loading is
desirable only for certain files.  Instead, enable the feature for
specific source files with file-local variable bindings.  For example,
you could do it by writing this text in the source file's first line:

@example
-*-byte-compile-dynamic: t;-*-
@end example

@defvar byte-compile-dynamic
If this is non-@code{nil}, the byte compiler generates compiled files
that are set up for dynamic function loading.
@end defvar

@defun fetch-bytecode function
If @var{function} is a byte-code function object, this immediately
finishes loading the byte code of @var{function} from its
byte-compiled file, if it is not fully loaded already.  Otherwise,
it does nothing.  It always returns @var{function}.
@end defun

@node Eval During Compile
@section Evaluation During Compilation
@cindex eval during compilation

  These features permit you to write code to be evaluated during
compilation of a program.

@defmac eval-and-compile body@dots{}
This form marks @var{body} to be evaluated both when you compile the
containing code and when you run it (whether compiled or not).

You can get a similar result by putting @var{body} in a separate file
and referring to that file with @code{require}.  That method is
preferable when @var{body} is large.  Effectively @code{require} is
automatically @code{eval-and-compile}, the package is loaded both when
compiling and executing.

@code{autoload} is also effectively @code{eval-and-compile} too.  It's
recognized when compiling, so uses of such a function don't produce
``not known to be defined'' warnings.

Most uses of @code{eval-and-compile} are fairly sophisticated.

If a macro has a helper function to build its result, and that macro
is used both locally and outside the package, then
@code{eval-and-compile} should be used to get the helper both when
compiling and then later when running.

If functions are defined programmatically (with @code{fset} say), then
@code{eval-and-compile} can be used to have that done at compile-time
as well as run-time, so calls to those functions are checked (and
warnings about ``not known to be defined'' suppressed).
@end defmac

@defmac eval-when-compile body@dots{}
This form marks @var{body} to be evaluated at compile time but not when
the compiled program is loaded.  The result of evaluation by the
compiler becomes a constant which appears in the compiled program.  If
you load the source file, rather than compiling it, @var{body} is
evaluated normally.

@cindex compile-time constant
If you have a constant that needs some calculation to produce,
@code{eval-when-compile} can do that at compile-time.  For example,

@lisp
(defvar my-regexp
  (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))
@end lisp

@cindex macros, at compile time
If you're using another package, but only need macros from it (the
byte compiler will expand those), then @code{eval-when-compile} can be
used to load it for compiling, but not executing.  For example,

@lisp
(eval-when-compile
  (require 'my-macro-package))
@end lisp

The same sort of thing goes for macros and @code{defsubst} functions
defined locally and only for use within the file.  They are needed for
compiling the file, but in most cases they are not needed for
execution of the compiled file.  For example,

@lisp
(eval-when-compile
  (unless (fboundp 'some-new-thing)
    (defmacro 'some-new-thing ()
      (compatibility code))))
@end lisp

@noindent
This is often good for code that's only a fallback for compatibility
with other versions of Emacs.

@strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common
Lisp idiom @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the
Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
to what @code{eval-when-compile} does.
@end defmac

@node Compiler Errors
@section Compiler Errors
@cindex compiler errors
@cindex byte-compiler errors

  Error and warning messages from byte compilation are printed in a
buffer named @file{*Compile-Log*}.  These messages include file names
and line numbers identifying the location of the problem.  The usual
Emacs commands for operating on compiler output can be used on these
messages.

  When an error is due to invalid syntax in the program, the byte
compiler might get confused about the error's exact location.  One way
to investigate is to switch to the buffer @w{@file{ *Compiler
Input*}}.  (This buffer name starts with a space, so it does not show
up in the Buffer Menu.)  This buffer contains the program being
compiled, and point shows how far the byte compiler was able to read;
the cause of the error might be nearby.  @xref{Syntax Errors}, for
some tips for locating syntax errors.

@cindex byte-compiler warnings
@cindex free variable, byte-compiler warning
@cindex reference to free variable, compilation warning
@cindex function not known to be defined, compilation warning
  A common type of warning issued by the byte compiler is for
functions and variables that were used but not defined.  Such warnings
report the line number for the end of the file, not the locations
where the missing functions or variables were used; to find these, you
must search the file manually.

  If you are sure that a warning message about a missing function or
variable is unjustified, there are several ways to suppress it:

@itemize @bullet
@item
You can suppress the warning for a specific call to a function
@var{func} by conditionalizing it on an @code{fboundp} test, like
this:

@example
(if (fboundp '@var{func}) ...(@var{func} ...)...)
@end example

@noindent
The call to @var{func} must be in the @var{then-form} of the
@code{if}, and @var{func} must appear quoted in the call to
@code{fboundp}.  (This feature operates for @code{cond} as well.)

@item
Likewise, you can suppress the warning for a specific use of a
variable @var{variable} by conditionalizing it on a @code{boundp}
test:

@example
(if (boundp '@var{variable}) ...@var{variable}...)
@end example

@noindent
The reference to @var{variable} must be in the @var{then-form} of the
@code{if}, and @var{variable} must appear quoted in the call to
@code{boundp}.

@item
You can tell the compiler that a function is defined using
@code{declare-function}.  @xref{Declaring Functions}.

@item
Likewise, you can tell the compiler that a variable is defined using
@code{defvar} with no initial value.  (Note that this marks the
variable as special, i.e.@: dynamically bound, but only within the
current lexical scope, or file if at top-level.)  @xref{Defining
Variables}.
@end itemize

  You can also suppress compiler warnings within a certain expression
using the @code{with-suppressed-warnings} macro:

@defspec with-suppressed-warnings warnings body@dots{}
In execution, this is equivalent to @code{(progn @var{body}...)}, but
the compiler does not issue warnings for the specified conditions in
@var{body}.  @var{warnings} is an associative list of warning symbols
and function/variable symbols they apply to.  For instance, if you
wish to call an obsolete function called @code{foo}, but want to
suppress the compilation warning, say:

@lisp
(with-suppressed-warnings ((obsolete foo))
  (foo ...))
@end lisp
@end defspec

For more coarse-grained suppression of compiler warnings, you can use
the @code{with-no-warnings} construct:

@c This is implemented with a defun, but conceptually it is
@c a special form.

@defspec with-no-warnings body@dots{}
In execution, this is equivalent to @code{(progn @var{body}...)},
but the compiler does not issue warnings for anything that occurs
inside @var{body}.

We recommend that you use @code{with-suppressed-warnings} instead, but
if you do use this construct, that you use it around the smallest
possible piece of code to avoid missing possible warnings other than
one you intend to suppress.
@end defspec

  Byte compiler warnings can be controlled more precisely by setting
the variable @code{byte-compile-warnings}.  See its documentation
string for details.

@vindex byte-compile-error-on-warn
  Sometimes you may wish the byte-compiler warnings to be reported
using @code{error}.  If so, set @code{byte-compile-error-on-warn} to a
non-@code{nil} value.

@node Byte-Code Objects
@section Byte-Code Function Objects
@cindex compiled function
@cindex byte-code function
@cindex byte-code object

  Byte-compiled functions have a special data type: they are
@dfn{byte-code function objects}.  Whenever such an object appears as
a function to be called, Emacs uses the byte-code interpreter to
execute the byte-code.

  Internally, a byte-code function object is much like a vector; its
elements can be accessed using @code{aref}.  Its printed
representation is like that for a vector, with an additional @samp{#}
before the opening @samp{[}.  It must have at least four elements;
there is no maximum number, but only the first six elements have any
normal use.  They are:

@table @var
@item argdesc
The descriptor of the arguments.  This can either be a list of
arguments, as described in @ref{Argument List}, or an integer encoding
the required number of arguments.  In the latter case, the value of
the descriptor specifies the minimum number of arguments in the bits
zero to 6, and the maximum number of arguments in bits 8 to 14.  If
the argument list uses @code{&rest}, then bit 7 is set; otherwise it's
cleared.

If @var{argdesc} is a list, the arguments will be dynamically bound
before executing the byte code.  If @var{argdesc} is an integer, the
arguments will be instead pushed onto the stack of the byte-code
interpreter, before executing the code.

@item byte-code
The string containing the byte-code instructions.

@item constants
The vector of Lisp objects referenced by the byte code.  These include
symbols used as function names and variable names.

@item stacksize
The maximum stack size this function needs.

@item docstring
The documentation string (if any); otherwise, @code{nil}.  The value may
be a number or a list, in case the documentation string is stored in a
file.  Use the function @code{documentation} to get the real
documentation string (@pxref{Accessing Documentation}).

@item interactive
The interactive spec (if any).  This can be a string or a Lisp
expression.  It is @code{nil} for a function that isn't interactive.
@end table

Here's an example of a byte-code function object, in printed
representation.  It is the definition of the command
@code{backward-sexp}.

@example
#[256
  "\211\204^G^@@\300\262^A\301^A[!\207"
  [1 forward-sexp]
  3
  1793299
  "^p"]
@end example

  The primitive way to create a byte-code object is with
@code{make-byte-code}:

@defun make-byte-code &rest elements
This function constructs and returns a byte-code function object
with @var{elements} as its elements.
@end defun

  You should not try to come up with the elements for a byte-code
function yourself, because if they are inconsistent, Emacs may crash
when you call the function.  Always leave it to the byte compiler to
create these objects; it makes the elements consistent (we hope).

@node Disassembly
@section Disassembled Byte-Code
@cindex disassembled byte-code

  People do not write byte-code; that job is left to the byte
compiler.  But we provide a disassembler to satisfy a cat-like
curiosity.  The disassembler converts the byte-compiled code into
human-readable form.

  The byte-code interpreter is implemented as a simple stack machine.
It pushes values onto a stack of its own, then pops them off to use them
in calculations whose results are themselves pushed back on the stack.
When a byte-code function returns, it pops a value off the stack and
returns it as the value of the function.

  In addition to the stack, byte-code functions can use, bind, and set
ordinary Lisp variables, by transferring values between variables and
the stack.

@deffn Command disassemble object &optional buffer-or-name
This command displays the disassembled code for @var{object}.  In
interactive use, or if @var{buffer-or-name} is @code{nil} or omitted,
the output goes in a buffer named @file{*Disassemble*}.  If
@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the
name of an existing buffer.  Then the output goes there, at point, and
point is left before the output.

The argument @var{object} can be a function name, a lambda expression
(@pxref{Lambda Expressions}), or a byte-code object (@pxref{Byte-Code
Objects}).  If it is a lambda expression, @code{disassemble} compiles
it and disassembles the resulting compiled code.
@end deffn

  Here are two examples of using the @code{disassemble} function.  We
have added explanatory comments to help you relate the byte-code to the
Lisp source; these do not appear in the output of @code{disassemble}.

@example
@group
(defun factorial (integer)
  "Compute factorial of an integer."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
     @result{} factorial
@end group

@group
(factorial 4)
     @result{} 24
@end group

@group
(disassemble 'factorial)
     @print{} byte-code for factorial:
 doc: Compute factorial of an integer.
 args: (integer)
@end group

@group
0   varref   integer      ; @r{Get the value of @code{integer} and}
                          ;   @r{push it onto the stack.}
1   constant 1            ; @r{Push 1 onto stack.}
@end group
@group
2   eqlsign               ; @r{Pop top two values off stack, compare}
                          ;   @r{them, and push result onto stack.}
@end group
@group
3   goto-if-nil 1         ; @r{Pop and test top of stack;}
                          ;   @r{if @code{nil}, go to 1, else continue.}
6   constant 1            ; @r{Push 1 onto top of stack.}
7   return                ; @r{Return the top element of the stack.}
@end group
@group
8:1 varref   integer      ; @r{Push value of @code{integer} onto stack.}
9   constant factorial    ; @r{Push @code{factorial} onto stack.}
10  varref   integer      ; @r{Push value of @code{integer} onto stack.}
11  sub1                  ; @r{Pop @code{integer}, decrement value,}
                          ;   @r{push new value onto stack.}
12  call     1            ; @r{Call function @code{factorial} using first}
                          ;   @r{(i.e., top) stack element as argument;}
                          ;   @r{push returned value onto stack.}
@end group
@group
13 mult                   ; @r{Pop top two values off stack, multiply}
                          ;   @r{them, and push result onto stack.}
14 return                 ; @r{Return the top element of the stack.}
@end group
@end example

The @code{silly-loop} function is somewhat more complex:

@example
@group
(defun silly-loop (n)
  "Return time before and after N iterations of a loop."
  (let ((t1 (current-time-string)))
    (while (> (setq n (1- n))
              0))
    (list t1 (current-time-string))))
     @result{} silly-loop
@end group

@group
(disassemble 'silly-loop)
     @print{} byte-code for silly-loop:
 doc: Return time before and after N iterations of a loop.
 args: (n)
@end group

@group
0   constant current-time-string  ; @r{Push @code{current-time-string}}
                                  ;   @r{onto top of stack.}
@end group
@group
1   call     0            ; @r{Call @code{current-time-string} with no}
                          ;   @r{argument, push result onto stack.}
@end group
@group
2   varbind  t1           ; @r{Pop stack and bind @code{t1} to popped value.}
@end group
@group
3:1 varref   n            ; @r{Get value of @code{n} from the environment}
                          ;   @r{and push the value on the stack.}
4   sub1                  ; @r{Subtract 1 from top of stack.}
@end group
@group
5   dup                   ; @r{Duplicate top of stack; i.e., copy the top}
                          ;   @r{of the stack and push copy onto stack.}
6   varset   n            ; @r{Pop the top of the stack,}
                          ;   @r{and bind @code{n} to the value.}

;; @r{(In effect, the sequence @code{dup varset} copies the top of the stack}
;; @r{into the value of @code{n} without popping it.)}
@end group

@group
7   constant 0            ; @r{Push 0 onto stack.}
8   gtr                   ; @r{Pop top two values off stack,}
                          ;   @r{test if @var{n} is greater than 0}
                          ;   @r{and push result onto stack.}
@end group
@group
9   goto-if-not-nil 1     ; @r{Goto 1 if @code{n} > 0}
                          ;   @r{(this continues the while loop)}
                          ;   @r{else continue.}
@end group
@group
12  varref   t1           ; @r{Push value of @code{t1} onto stack.}
13  constant current-time-string  ; @r{Push @code{current-time-string}}
                                  ;   @r{onto the top of the stack.}
14  call     0            ; @r{Call @code{current-time-string} again.}
@end group
@group
15  unbind   1            ; @r{Unbind @code{t1} in local environment.}
16  list2                 ; @r{Pop top two elements off stack, create a}
                          ;   @r{list of them, and push it onto stack.}
17  return                ; @r{Return value of the top of stack.}
@end group
@end example

@node Native Compilation
@chapter Compilation of Lisp to Native Code
@cindex native compilation
@cindex compilation to native code (Emacs Lisp)

@cindex native code
  In addition to the byte-compilation, described in @ref{Byte
Compilation, the previous chapter}, Emacs can also optionally compile
Lisp function definitions into a true compiled code, known as
@dfn{native code}.  This feature uses the @file{libgccjit} library,
which is part of the GCC distribution, and requires that Emacs be
built with support for using that library.  It also requires to have
GCC and Binutils (the assembler and linker) available on your system
for you to be able to native-compile Lisp code.

@vindex native-compile@r{, a Lisp feature}
  To determine whether the current Emacs process can produce and load
natively-compiled Lisp code, test whether the @code{native-compile}
feature is available (@pxref{Named Features}).  Alternatively, call
@code{native-comp-available-p} (@pxref{Native-Compilation Functions}).

  Unlike byte-compiled code, natively-compiled Lisp code is executed
directly by the machine's hardware, and therefore runs at full speed
that the host CPU can provide.  The resulting speedup generally
depends on what the Lisp code does, but is usually 2.5 to 5 times
faster than the corresponding byte-compiled code.

  Since native code is generally incompatible between different
systems, the natively-compiled code is @emph{not} transportable from
one machine to another, it can only be used on the same machine where
it was produced or on very similar ones (having the same CPU and
run-time libraries).  The transportability of natively-compiled code
is the same as that of shared libraries (@file{.so} or @file{.dll}
files).

  Libraries of natively-compiled code include crucial dependencies on
Emacs Lisp primitives (@pxref{What Is a Function}) and their calling
conventions, and thus Emacs usually won't load natively-compiled code
produced by earlier or later Emacs versions; native compilation of the
same Lisp code by a different Emacs version will usually produce a
natively-compiled library under a unique file name that only that
version of Emacs will be able to load.  However, the use of unique
file names allows to have in the same directory several versions of
the same Lisp library natively-compiled by several different versions
of Emacs.

@vindex no-native-compile
  A non-@code{nil} file-local variable binding of
@code{no-byte-compile} (@pxref{Byte Compilation}) also disables the
native compilation of that file.  In addition, a similar variable
@code{no-native-compile} disables just the native compilation of the
file.  If both @code{no-byte-compile} and @code{no-native-compile} are
specified, the former takes precedence.

@menu
* Native-Compilation Functions::  Functions to natively-compile Lisp.
* Native-Compilation Variables::  Variables controlling native compilation.
@end menu

@node Native-Compilation Functions
@section Native-Compilation Functions
@cindex native-compilation functions

   Native-Compilation is implemented as a side effect of
byte-compilation (@pxref{Byte Compilation}).  Thus, compiling Lisp
code natively always produces its byte code as well, and therefore all
the rules and caveats of preparing Lisp code for byte compilation
(@pxref{Compilation Functions}) are valid for native-compilation as
well.

   You can natively-compile either a single function or macro
definition, or a whole file of Lisp code, with the
@code{native-compile} function.  Natively-compiling a file will
produce both the corresponding @file{.elc} file with byte code and the
@file{.eln} file with native code.

@findex native-comp-limple-mode
@vindex native-comp-verbose
  Native compilation might produce warning or error messages; these
are normally recorded in the buffer called
@file{*Native-compile-Log*}.  In interactive sessions, it uses the
special @acronym{LIMPLE} mode (@code{native-comp-limple-mode}), which
sets up @code{font-lock} as appropriate for this log, and is otherwise
the same as Fundamental mode.  Logging of messages resulting from
native-compilation can be controlled by the @code{native-comp-verbose}
variable (@pxref{Native-Compilation Variables}).

  When Emacs is run non-interactively, messages produced by
native-compilation are reported by calling @code{message}
(@pxref{Displaying Messages}), and are usually displayed on the
standard error stream of the terminal from which Emacs was invoked.

@defun native-compile function-or-file &optional output
This function compiles @var{function-or-file} into native code.  The
argument @var{function-or-file} can be a function symbol, a Lisp form,
or a name (a string) of the file which contains the Emacs Lisp source
code to compile.  If the optional argument @var{output} is provided,
it must be a string specifying the name of the file to write the
compiled code into.  Otherwise, if @var{function-or-file} is a
function or a Lisp form, this function returns the compiled object,
and if @var{function-or-file} is a file name, the function returns the
full absolute name of the file it created for the compiled code.  The
output file is by default given the @file{.eln} extension.

This function runs the final phase of the native compilation, which
invokes GCC via @file{libgccjit}, in a separate subprocess, which
invokes the same Emacs executable as the process that called this
function.
@end defun

@defun batch-native-compile
This function runs native-compilation on files specified on the Emacs
command line in batch mode.  It must be used only in a batch execution
of Emacs, as it kills Emacs upon completion of the compilation.  If
one or more of the files fail to compile, the Emacs process will
attempt to compile all the other files, and will terminate with a
non-zero status code.
@end defun

Native compilation can be run entirely asynchronously, in a subprocess
of the main Emacs process.  This leaves the main Emacs process free to
use while the compilation runs in the background.  This is the method
used by Emacs to natively-compile any Lisp file or byte-compiled Lisp
file that is loaded into Emacs, when no natively-compiled file for it
is available.

@defun native-compile-async files &optional recursively load selector
This function compiles the named @var{files} asynchronously.  The
argument @var{files} should be a single file name (a string) or a list
of one or more file and/or directory names.  If directories are
present in the list, the optional argument @var{recursively} should be
non-@code{nil} to cause the compilation to recurse into those
directories.  If @var{load} is non-@code{nil}, Emacs will load each
file that it succeeded to compile.  The optional argument
@var{selector} allows control of which of @var{files} will be
compiled; it can have one of the following values:

@table @asis
@item @code{nil} or omitted
Select all the files and directories in @var{files}.
@item a regular expression string
Select the files and directories whose names match the regexp.
@item a function
A predicate function, which will be called with each file and
directory in @var{files}, and should return non-@code{nil} if the file
or the directory should be selected for compilation.
@end table

On systems with multiple CPU execution units, when @var{files} names
more than one file, this function will normally start several
compilation subprocesses in parallel, under the control of
@code{native-comp-async-jobs-number} (@pxref{Native-Compilation
Variables}).
@end defun

  The following function allows Lisp programs to test whether
native-compilation is available at runtime.

@defun native-comp-available-p
This function returns non-@code{nil} if the running Emacs process has
the native-compilation support compiled into it.  On systems that load
@file{libgccjit} dynamically, it also makes sure that library is
available and can be loaded.  Lisp programs that need to know up front
whether native-compilation is available should use this predicate.
@end defun

@node Native-Compilation Variables
@section Native-Compilation Variables
@cindex native-compilation variables

  This section documents the variables that control
native-compilation.

@defopt native-comp-speed
This variable specifies the optimization level for native compilation.
Its value should be a number between @minus{}1 and 3.  Values between
0 and 3 specify the optimization levels equivalent to the
corresponding compiler @option{-O0}, @option{-O1}, etc.@: command-line
options of the compiler.  The value @minus{}1 means disable
native-compilation; functions and files will be only byte-compiled.
The default value is 2.
@end defopt

@defopt native-comp-debug
This variable specifies the level of debugging information produced by
native-compilation.  Its value should be a number between zero and 3,
with the following meaning:

@table @asis
@item 0
No debugging output.  This is the default.
@item 1
Emit debugging symbols with the native code.  This allows easier
debugging of the native code with debuggers such as @command{gdb}.
@item 2
Like 1, and in addition dump pseudo-C code.
@item 3
Like 2, and in addition dump the GCC intermediate passes and
@file{libgccjit} log file.
@end table
@end defopt

@defopt native-comp-verbose
This variable controls the verbosity of native-compilation by
suppressing some or all of the log messages emitted by it.  If its
value is zero, the default, all of the log messages are suppressed.
Setting it to a value between 1 and 3 will allow logging of the
messages whose level is above the value.  The values have the
following interpretations:

@table @asis
@item 0
No logging.  This is the default.
@item 1
Log the final @acronym{LIMPLE} representation of the code.
@item 2
Log the @acronym{LAP}, the final @acronym{LIMPLE}, and some additional
pass info.
@item 3
Maximum verbosity: log everything.
@end table
@end defopt

@defopt native-comp-async-jobs-number
This variable determines the maximum number of native-compilation
subprocesses that will be started simultaneously.  It should be a
non-negative number.  The default value is zero, which means use half
the number of the CPU execution units, or 1 if the CPU has only one
execution unit.
@end defopt

@defopt native-comp-async-report-warnings-errors
If this variable's value is non-@code{nil}, warnings and errors from
asynchronous native-compilation subprocesses are reported in the main
Emacs session.  The default is @code{t}.
@end defopt

@defopt native-comp-async-query-on-exit
If this variable's value is non-nil, Emacs will query upon exiting
whether to exit and kill any asynchronous native-compilation
subprocesses that are still running, thus preventing the corresponding
@file{.eln} files from being written.  If the value is @code{nil}, the
default, Emacs will kill these subprocesses without querying.
@end defopt

debug log:

solving 09a3973d64 ...
found 09a3973d64 in https://yhetil.org/emacs-devel/87bl9lmfmx.fsf@tcd.ie/
found f0787795ca in https://git.savannah.gnu.org/cgit/emacs.git
preparing index
index prepared:
100644 f0787795cac195b34e99a2329e891c9e0dec68f0	doc/lispref/compile.texi

applying [1/1] https://yhetil.org/emacs-devel/87bl9lmfmx.fsf@tcd.ie/
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index f0787795ca..09a3973d64 100644

Checking patch doc/lispref/compile.texi...
Applied patch doc/lispref/compile.texi cleanly.

index at:
100644 09a3973d6489e29df176436e79f042d9075d6cd2	doc/lispref/compile.texi

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).