emscripten/src/settings.js at main · emscripten-core/emscripten · GitHub

History

2326 lines (2093 loc) · 102 KB

Raw

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

// Settings that control the emscripten compiler. These are available to the

// python code and also as global variables when the JS compiler runs. They

// are set via the command line. For example:

// emcc -sOPTION1=VALUE1 -sOPTION2=ITEM1,ITEM2 [..other stuff..]

// For convenience and readability ``-sOPTION`` expands to ``-sOPTION=1``

// and ``-sNO_OPTION`` expands to ``-sOPTION=0`` (assuming OPTION is a valid

// option).

// See https://github.com/emscripten-core/emscripten/wiki/Code-Generation-Modes/

// Note that the values here are the defaults which can be affected either

// directly via ``-s`` flags or indirectly via other options (e.g. -O1,2,3)

// These flags should only have an effect when compiling to JS, so there

// should not be a need to have them when just compiling source to

// bitcode. However, there will also be no harm either, so it is ok to.

// Settings in this file can be directly set from the command line. Internal

// settings that are not part of the user ABI live in the settings_internal.js.

// In general it is best to pass the same arguments at both compile and link

// time, as whether wasm object files are used or not affects when codegen

// happens (without wasm object files, codegen is done entirely during

// link; otherwise, it is during compile). Flags affecting codegen must

// be passed when codegen happens, so to let a build easily switch when codegen

// happens (LTO vs normal), pass the flags at both times. The flags are also

// annotated in this file:

// [link] - Should be passed at link time. This is the case for all JS flags,

// as we emit JS at link (and that is most of the flags here, and

// hence the default).

// [compile+link] - A flag that has an effect at both compile and link time,

// basically any time emcc is invoked. The same flag should be

// passed at both times in most cases.

// If not otherwise specified, a flag is [link]. Note that no flag is only

// relevant during compile time, as during link we may do codegen for system

// libraries and other support code, so all flags are either link or

// compile+link.

// Tuning

// Whether we should add runtime assertions. This affects both JS and how

// system libraries are built.

// ASSERTIONS == 2 gives even more runtime checks, that may be very slow. That

// includes internal dlmalloc assertions, for example.

// ASSERTIONS defaults to 0 in optimized builds (-O1 and above).

// [link]

var ASSERTIONS = 1;

// Chooses what kind of stack smash checks to emit to generated code:

// Building with ASSERTIONS=1 causes STACK_OVERFLOW_CHECK default to 1.

// Since ASSERTIONS=1 is the default at -O0, which itself is the default

// optimization level this means that this setting also effectively

// defaults to 1, absent any other settings:

// - 0: Stack overflows are not checked.

// - 1: Adds a security cookie at the top of the stack, which is checked at end

// of each tick and at exit (practically zero performance overhead)

// - 2: Same as above, but also runs a binaryen pass which adds a check to all

// stack pointer assignments. Has a small performance cost.

// [link]

var STACK_OVERFLOW_CHECK = 0;

// When :ref`STACK_OVERFLOW_CHECK` is enabled we also check writes to address

// zero. This can help detect NULL pointer usage. If you want to skip this

// extra check (for example, if you want reads from the address zero to always

// return zero) you can disable this here. This setting has no effect when

// :ref:`STACK_OVERFLOW_CHECK` is disabled.

var CHECK_NULL_WRITES = true;

// When set to 1, will generate more verbose output during compilation.

// [general]

var VERBOSE = false;

// Whether we will run the main() function. Disable if you embed the generated

// code in your own, and will call main() yourself at the right time (which you

// can do with Module.callMain(), with an optional parameter of commandline args).

// [link]

var INVOKE_RUN = true;

// If 0, support for shutting down the runtime is not emitted into the build.

// This means that the program is not quit when main() completes, but execution

// will yield to the event loop of the JS environment, allowing event handlers

// to run afterwards. If 0, C++ global destructors will not be emitted into the

// build either, to save on code size. Calling exit() will throw an unwinding

// exception, but will not shut down the runtime.

// Set this to 1 if you do want to retain the ability to shut down the program.

// If 1, then completing main() will by default call exit(), unless a refcount

// keeps the runtime alive. Call emscripten_exit_with_live_runtime() to finish

// main() while keeping the runtime alive. Calling emscripten_force_exit() will

// shut down the runtime, invoking atexit()s, and flushing stdio streams.

// This setting is controlled automatically in :ref:`STANDALONE_WASM` mode:

// - For a command (has a main function) this is always 1

// - For a reactor (no main function) this is always 0

// For more details, see documentation for emscripten_force_exit() and

// emscripten_exit_with_live_runtime().

// [link]

var EXIT_RUNTIME = false;

// The total stack size. There is no way to enlarge the stack, so this

// value must be large enough for the program's requirements. If

// assertions are on, we will assert on not exceeding this, otherwise,

// it will fail silently.

// [link]

var STACK_SIZE = 64*1024;

// What malloc()/free() to use, out of:

// - dlmalloc - a powerful general-purpose malloc

// - emmalloc - a simple and compact malloc designed for emscripten

// - emmalloc-debug - use emmalloc and add extra assertion checks

// - emmalloc-memvalidate - use emmalloc with assertions+heap consistency

// checking.

// - emmalloc-verbose - use emmalloc with assertions + verbose logging.

// - emmalloc-memvalidate-verbose - use emmalloc with assertions + heap

// consistency checking + verbose logging.

// - mimalloc - a powerful multithreaded allocator. This is recommended in

// large applications that have malloc() contention, but it is

// larger and uses more memory.

// - none - no malloc() implementation is provided, but you must implement

// malloc() and free() yourself.

// dlmalloc is necessary for split memory and other special modes, and will be

// used automatically in those cases.

// In general, if you don't need one of those special modes, and if you don't

// allocate very many small objects, you should use emmalloc since it's

// smaller. Otherwise, if you do allocate many small objects, dlmalloc

// is usually worth the extra size. dlmalloc is also a good choice if you want

// the extra security checks it does (such as noticing metadata corruption in

// its internal data structures, which emmalloc does not do).

// [link]

var MALLOC = "dlmalloc";

// If 1, then when malloc would fail we abort(). This is nonstandard behavior,

// but makes sense for the web since we have a fixed amount of memory that

// must all be allocated up front, and so (a) failing mallocs are much more

// likely than on other platforms, and (b) people need a way to find out

// how big that initial allocation (INITIAL_MEMORY) must be.

// If you set this to 0, then you get the standard malloc behavior of

// returning NULL (0) when it fails.

// Setting ALLOW_MEMORY_GROWTH turns this off, as in that mode we default to

// the behavior of trying to grow and returning 0 from malloc on failure, like

// a standard system would. However, you can still set this flag to override

// that. This is a mostly-backwards-compatible change. Previously this option

// was ignored when growth was on. The current behavior is that growth turns it

// off by default, so for users that never specified the flag nothing changes.

// But if you do specify it, it will have an effect now, which it did not

// previously. If you don't want that, just stop passing it in at link time.

// Note that this setting does not affect the behavior of operator new in C++.

// This function will always abort on allocation failure if exceptions are

// disabled.

// If you want new to return 0 on failure, use it with std::nothrow.

// [link]

var ABORTING_MALLOC = true;

// The initial amount of heap memory available to the program. This is the

// memory region available for dynamic allocations via `sbrk`, `malloc` and `new`.

// Unlike INITIAL_MEMORY, this setting allows the static and dynamic regions of

// your program's memory to independently grow. In most cases we recommend using

// this setting rather than `INITIAL_MEMORY`. However, this setting does not work

// for imported memories (e.g. when dynamic linking is used).

// [link]

var INITIAL_HEAP = 16777216;

// The initial amount of memory to use. Using more memory than this will

// cause us to expand the heap, which can be costly with typed arrays:

// we need to copy the old heap into a new one in that case.

// If ALLOW_MEMORY_GROWTH is set, this initial amount of memory can increase

// later; if not, then it is the final and total amount of memory.

// By default, this value is calculated based on INITIAL_HEAP, STACK_SIZE,

// as well the size of static data in input modules.

// (This option was formerly called TOTAL_MEMORY.)

// [link]

var INITIAL_MEMORY = -1;

// Set the maximum size of memory in the wasm module (in bytes). This is only

// relevant when ALLOW_MEMORY_GROWTH is set, as without growth, the size of

// INITIAL_MEMORY is the final size of memory anyhow.

// Note that the default value here is 2GB, which means that by default if you

// enable memory growth then we can grow up to 2GB but no higher. 2GB is a

// natural limit for several reasons:

// * If the maximum heap size is over 2GB, then pointers must be unsigned in

// JavaScript, which increases code size. We don't want memory growth builds

// to be larger unless someone explicitly opts in to >2GB+ heaps.

// * Historically no VM has supported more >2GB+, and only recently (Mar 2020)

// has support started to appear. As support is limited, it's safer for

// people to opt into >2GB+ heaps rather than get a build that may not

// work on all VMs.

// To use more than 2GB, set this to something higher, like 4GB.

// (This option was formerly called WASM_MEM_MAX and BINARYEN_MEM_MAX.)

// [link]

var MAXIMUM_MEMORY = 2147483648;

// If false, we abort with an error if we try to allocate more memory than

// we can (INITIAL_MEMORY). If true, we will grow the memory arrays at

// runtime, seamlessly and dynamically.

// See https://code.google.com/p/v8/issues/detail?id=3907 regarding

// memory growth performance in chrome.

// Note that growing memory means we replace the JS typed array views, as

// once created they cannot be resized. (In wasm we can grow the Memory, but

// still need to create new views for JS.)

// Setting this option on will disable ABORTING_MALLOC, in other words,

// ALLOW_MEMORY_GROWTH enables fully standard behavior, of both malloc

// returning 0 when it fails, and also of being able to allocate more

// memory from the system as necessary.

// [link]

var ALLOW_MEMORY_GROWTH = false;

// If ALLOW_MEMORY_GROWTH is true, this variable specifies the geometric

// overgrowth rate of the heap at resize. Specify MEMORY_GROWTH_GEOMETRIC_STEP=0

// to disable overgrowing the heap at all, or e.g.

// MEMORY_GROWTH_GEOMETRIC_STEP=1.0 to double the heap (+100%) at every grow step.

// The larger this value is, the more memory the WebAssembly heap overreserves

// to reduce performance hiccups coming from memory resize, and the smaller

// this value is, the more memory is conserved, at the performance of more

// stuttering when the heap grows. (profiled to be on the order of ~20 msecs)

// [link]

var MEMORY_GROWTH_GEOMETRIC_STEP = 0.20;

// Specifies a cap for the maximum geometric overgrowth size, in bytes. Use

// this value to constrain the geometric grow to not exceed a specific rate.

// Pass MEMORY_GROWTH_GEOMETRIC_CAP=0 to disable the cap and allow unbounded

// size increases.

// [link]

var MEMORY_GROWTH_GEOMETRIC_CAP = 96*1024*1024;

// If ALLOW_MEMORY_GROWTH is true and MEMORY_GROWTH_LINEAR_STEP == -1, then

// geometric memory overgrowth is utilized (above variable). Set

// MEMORY_GROWTH_LINEAR_STEP to a multiple of WASM page size (64KB), eg. 16MB to

// replace geometric overgrowth rate with a constant growth step size. When

// MEMORY_GROWTH_LINEAR_STEP is used, the variables MEMORY_GROWTH_GEOMETRIC_STEP

// and MEMORY_GROWTH_GEOMETRIC_CAP are ignored.

// [link]

var MEMORY_GROWTH_LINEAR_STEP = -1;

// The "architecture" to compile for. 0 means the default wasm32, 1 is

// the full end-to-end wasm64 mode, and 2 is wasm64 for clang/lld but lowered to

// wasm32 in Binaryen (such that it can run on wasm32 engines, while internally

// using i64 pointers).

// Nowadays we recommend using the more standard `-m64` or `--target=wasm64`

// flags, which do the same thing.

// Assumes WASM_BIGINT.

// [compile+link]

// [deprecated]

var MEMORY64 = 0;

// Sets the initial size of the table when MAIN_MODULE or SIDE_MODULE is used

// (and not otherwise). Normally Emscripten can determine the size of the table

// at link time, but in SPLIT_MODULE mode, wasm-split often needs to grow the

// table, so the table size baked into the JS for the instrumented build will be

// too small after the module is split. This is a hack to allow users to specify

// a large enough table size that can be consistent across both builds. This

// setting may be removed at any time and should not be used except in

// conjunction with SPLIT_MODULE and dynamic linking.

// [link]

var INITIAL_TABLE = -1;

// If true, allows more functions to be added to the table at runtime. This is

// necessary for dynamic linking, and set automatically in that mode.

// [link]

var ALLOW_TABLE_GROWTH = false;

// Where global data begins; the start of static memory.

// A GLOBAL_BASE of 1024 or above is useful for optimizing load/store offsets,

// as it enables the --low-memory-unused pass

// [link]

var GLOBAL_BASE = 1024;

// Where table slots (function addresses) are allocated.

// This must be at least 1 to reserve the zero slot for the null pointer.

// [link]

var TABLE_BASE = 1;

// Whether closure compiling is being run on this output

// [link]

var USE_CLOSURE_COMPILER = false;

// Deprecated: Use the standard warnings flags instead. e.g. ``-Wclosure``,

// ``-Wno-closure``, ``-Werror=closure``.

// options: 'quiet', 'warn', 'error'. If set to 'warn', Closure warnings are

// printed out to console. If set to 'error', Closure warnings are treated like

// errors, similar to -Werror compiler flag.

// [link]

// [deprecated]

var CLOSURE_WARNINGS = 'quiet';

// Ignore closure warnings and errors (like on duplicate definitions)

// [link]

var IGNORE_CLOSURE_COMPILER_ERRORS = false;

// If set to 1, each wasm module export is individually declared with a

// JavaScript "var" definition. This is the simple and recommended approach.

// However, this does increase code size (especially if you have many such

// exports), which can be avoided in an unsafe way by setting this to 0. In that

// case, no "var" is created for each export, and instead a loop (of small

// constant code size, no matter how many exports you have) writes all the

// exports received into the global scope. Doing so is dangerous since such

// modifications of the global scope can confuse external JS minifier tools, and

// also things can break if the scope the code is in is not the global scope

// (e.g. if you manually enclose them in a function scope).

// [link]

var DECLARE_ASM_MODULE_EXPORTS = true;

// If set to 1, prevents inlining. If 0, we will inline normally in LLVM.

// This does not affect the inlining policy in Binaryen.

// [compile]

var INLINING_LIMIT = false;

// If set to 1, perform an acorn pass that converts each HEAP access into a

// function call that uses DataView to enforce LE byte order for HEAP buffer;

// This makes generated JavaScript run on BE as well as LE machines. (If 0, only

// LE systems are supported). Does not affect generated wasm.

// [experimental]

var SUPPORT_BIG_ENDIAN = false;

// Check each write to the heap, for example, this will give a clear

// error on what would be segfaults in a native build (like dereferencing

// 0). See runtime_safe_heap.js for the actual checks performed.

// Set to value 1 to test for safe behavior for both Wasm+Wasm2JS builds.

// Set to value 2 to test for safe behavior for only Wasm builds. (notably,

// Wasm-only builds allow unaligned memory accesses. Note, however, that

// on some architectures unaligned accesses can be very slow, so it is still

// a good idea to verify your code with the more strict mode 1)

// [link]

var SAFE_HEAP = 0;

// Log out all SAFE_HEAP operations

// [link]

var SAFE_HEAP_LOG = false;

// Allows function pointers to be cast, wraps each call of an incorrect type

// with a runtime correction. This adds overhead and should not be used

// normally. Aside from making calls not fail, this tries to convert values as

// best it can. We use 64 bits (i64) to represent values, as if we wrote the

// sent value to memory and loaded the received type from the same memory (using

// truncs/extends/ reinterprets). This means that when types do not match the

// emulated values may not match (this is true of native too, for that matter -

// this is all undefined behavior). This approach appears good enough to

// support Python (the original motivation for this feature) and Glib (the

// continued motivation).

// [link]

var EMULATE_FUNCTION_POINTER_CASTS = false;

// Print out exceptions in emscriptened code.

// [link]

var EXCEPTION_DEBUG = false;

// Print out when we enter a library call (library*.js). You can also unset

// runtimeDebug at runtime for logging to cease, and can set it when you want

// it back. A simple way to set it in C++ is::

// emscripten_run_script("runtimeDebug = ...;");

// [link]

var LIBRARY_DEBUG = false;

// Print out all musl syscalls, including translating their numeric index

// to the string name, which can be convenient for debugging. (Other system

// calls are not numbered and already have clear names; use :ref:`LIBRARY_DEBUG`

// to get logging for all of them.)

// [link]

var SYSCALL_DEBUG = false;

// Log out socket/network data transfer.

// [link]

var SOCKET_DEBUG = false;

// Log dynamic linker information

// [link]

var DYLINK_DEBUG = 0;

// Register file system callbacks using trackingDelegate in library_fs.js

// [link]

var FS_DEBUG = false;

// A string containing either a WebSocket URL prefix (ws:// or wss://) or a

// complete RFC 6455 URL - "ws[s]:" "//" host [ ":" port ] path [ "?" query ].

// In the (default) case of only a prefix being specified the URL will be

// constructed from prefix + addr + ':' + port

// where addr and port are derived from the socket connect/bind/accept calls.

// [link]

var WEBSOCKET_URL = 'ws://';

// If 1, the POSIX sockets API uses a native bridge process server to proxy

// sockets calls from browser to native world.

// [link]

var PROXY_POSIX_SOCKETS = false;

// If enabled, the POSIX sockets API is backed by Node.js's ``node:net``

// module, giving real non-blocking outgoing TCP sockets with no WebSockets,

// proxy process or pthreads. This is the sockets counterpart to

// :ref:`NODERAWFS`: where :ref:`NODERAWFS` gives direct access to the host

// filesystem, this gives direct access to host sockets. It only works under

// node and is ignored elsewhere.

// It supports full TCP (outgoing connect plus bind, listen and accept for

// servers) and UDP. TCP clients use the public ``node:net`` API when possible,

// falling back to the private ``tcp_wrap``/``udp_wrap`` handles on older

// Node.js.

// It is event-driven. Socket readiness comes through the same

// ``emscripten_set_socket_*_callback`` hooks the WebSocket backend uses, so it

// works with existing readiness reactors. It cannot be combined with the

// WebSocket emulation or :ref:`PROXY_POSIX_SOCKETS`.

// It works under -pthread with :ref:`PROXY_TO_PTHREAD`, where main() and every socket

// syscall run on a single worker alongside the node handles and their event

// loop. As with the WebSocket backend, sharing a socket across threads under a

// plain -pthread build (without PROXY_TO_PTHREAD) is not supported.

// [link]

var NODERAWSOCKETS = false;

// A string containing a comma separated list of WebSocket subprotocols

// as would be present in the Sec-WebSocket-Protocol header.

// You can set 'null', if you don't want to specify it.

// [link]

var WEBSOCKET_SUBPROTOCOL = 'binary';

// Print out debugging information from our OpenAL implementation.

// [link]

var OPENAL_DEBUG = false;

// If 1, prints out debugging related to calls from ``emscripten_web_socket_*``

// functions in ``emscripten/websocket.h``.

// If 2, additionally traces bytes communicated via the sockets.

// [link]

var WEBSOCKET_DEBUG = false;

// Adds extra checks for error situations in the GL library. Can impact

// performance.

// [link]

var GL_ASSERTIONS = false;

// If enabled, prints out all API calls to WebGL contexts. (*very* verbose)

// [link]

var TRACE_WEBGL_CALLS = false;

// Enables more verbose debug printing of WebGL related operations. As with

// LIBRARY_DEBUG, this is toggleable at runtime with option GL.debug.

// [link]

var GL_DEBUG = false;

// When enabled, sets preserveDrawingBuffer in the context, to allow tests to

// work (but adds overhead)

// [link]

var GL_TESTING = false;

// How large GL emulation temp buffers are

// [link]

var GL_MAX_TEMP_BUFFER_SIZE = 2097152;

// Enables some potentially-unsafe optimizations in GL emulation code

// [link]

var GL_UNSAFE_OPTS = true;

// Forces support for all GLES2 features, not just the WebGL-friendly subset.

// [link]

var FULL_ES2 = false;

// If true, glGetString() for GL_VERSION and GL_SHADING_LANGUAGE_VERSION will

// return strings OpenGL ES format "Open GL ES ... (WebGL ...)" rather than the

// WebGL format. If false, the direct WebGL format strings are returned. Set

// this to true to make GL contexts appear like an OpenGL ES context in these

// version strings (at the expense of a little bit of added code size), and to

// false to make GL contexts appear like WebGL contexts and to save some bytes

// from the output.

// [link]

var GL_EMULATE_GLES_VERSION_STRING_FORMAT = true;

// If true, all GL extensions are advertised in unprefixed WebGL extension

// format, but also in desktop/mobile GLES/GL extension format with ``GL_``

// prefix.

// [link]

var GL_EXTENSIONS_IN_PREFIXED_FORMAT = true;

// If true, adds support for automatically enabling all GL extensions for

// GLES/GL emulation purposes. This takes up code size. If you set this to 0,

// you will need to manually enable the extensions you need.

// [link]

var GL_SUPPORT_AUTOMATIC_ENABLE_EXTENSIONS = true;

// If true, the function ``emscripten_webgl_enable_extension()`` can be called

// to enable any WebGL extension. If false, to save code size,

// ``emscripten_webgl_enable_extension()`` cannot be called to enable any of

// extensions 'ANGLE_instanced_arrays', 'OES_vertex_array_object',

// 'WEBGL_draw_buffers', 'WEBGL_multi_draw',

// 'WEBGL_draw_instanced_base_vertex_base_instance', or

// 'WEBGL_multi_draw_instanced_base_vertex_base_instance',

// but the dedicated functions ``emscripten_webgl_enable_*()``

// found in html5.h are used to enable each of those extensions.

// This way code size is increased only for the extensions that are actually used.

// N.B. if setting this to 0, GL_SUPPORT_AUTOMATIC_ENABLE_EXTENSIONS must be set

// to zero as well.

// [link]

var GL_SUPPORT_SIMPLE_ENABLE_EXTENSIONS = true;

// If set to 0, Emscripten GLES2->WebGL translation layer does not track the

// kind of GL errors that exist in GLES2 but do not exist in WebGL. Setting

// this to 0 saves code size. (Good to keep at 1 for development)

// [link]

var GL_TRACK_ERRORS = true;

// If true, GL contexts support the explicitSwapControl context creation flag.

// Set to 0 to save a little bit of space on projects that do not need it.

// [link]

var GL_SUPPORT_EXPLICIT_SWAP_CONTROL = false;

// If true, calls to glUniform*fv and glUniformMatrix*fv utilize a pool of

// preallocated temporary buffers for common small sizes to avoid generating

// temporary garbage for WebGL 1. Disable this to optimize generated size of the

// GL library a little bit, at the expense of generating garbage in WebGL 1. If

// you are only using WebGL 2 and do not support WebGL 1, this is not needed and

// you can turn it off.

// [link]

var GL_POOL_TEMP_BUFFERS = true;

// If true, enables support for the EMSCRIPTEN_explicit_uniform_location WebGL

// extension. See docs/EMSCRIPTEN_explicit_uniform_location.txt

var GL_EXPLICIT_UNIFORM_LOCATION = false;

// If true, enables support for the EMSCRIPTEN_uniform_layout_binding WebGL

// extension. See docs/EMSCRIPTEN_explicit_uniform_binding.txt

var GL_EXPLICIT_UNIFORM_BINDING = false;

// Deprecated. Pass -sMAX_WEBGL_VERSION=2 to target WebGL 2.0.

// [link]

var USE_WEBGL2 = false;

// Specifies the lowest WebGL version to target. Pass -sMIN_WEBGL_VERSION=1

// to enable targeting WebGL 1, and -sMIN_WEBGL_VERSION=2 to drop support

// for WebGL 1.0

// [link]

var MIN_WEBGL_VERSION = 1;

// Specifies the highest WebGL version to target. Pass -sMAX_WEBGL_VERSION=2

// to enable targeting WebGL 2. If WebGL 2 is enabled, some APIs (EGL, GLUT, SDL)

// will default to creating a WebGL 2 context if no version is specified.

// Note that there is no automatic fallback to WebGL1 if WebGL2 is not supported

// by the user's device, even if you build with both WebGL1 and WebGL2

// support, as that may not always be what the application wants. If you want

// such a fallback, you can try to create a context with WebGL2, and if that

// fails try to create one with WebGL1.

// [link]

var MAX_WEBGL_VERSION = 1;

// If true, emulates some WebGL 1 features on WebGL 2 contexts, meaning that

// applications that use WebGL 1/GLES 2 can initialize a WebGL 2/GLES3 context,

// but still keep using WebGL1/GLES 2 functionality that no longer is supported

// in WebGL2/GLES3. Currently this emulates GL_EXT_shader_texture_lod extension

// in GLSL ES 1.00 shaders, support for unsized internal texture formats, and the

// GL_HALF_FLOAT_OES != GL_HALF_FLOAT mixup.

// [link]

var WEBGL2_BACKWARDS_COMPATIBILITY_EMULATION = false;

// Forces support for all GLES3 features, not just the WebGL2-friendly subset.

// This automatically turns on FULL_ES2 and WebGL2 support.

// [link]

var FULL_ES3 = false;

// Includes code to emulate various desktop GL features. Incomplete but useful

// in some cases, see

// http://kripken.github.io/emscripten-site/docs/porting/multimedia_and_graphics/OpenGL-support.html

// [link]

var LEGACY_GL_EMULATION = false;

// If you specified LEGACY_GL_EMULATION = 1 and only use fixed function pipeline

// in your code, you can also set this to 1 to signal the GL emulation layer

// that it can perform extra optimizations by knowing that the user code does

// not use shaders at all. If LEGACY_GL_EMULATION = 0, this setting has no

// effect.

// [link]

var GL_FFP_ONLY = false;

// If you want to create the WebGL context up front in JS code, set this to 1

// and set Module['preinitializedWebGLContext'] to a precreated WebGL context.

// WebGL initialization afterwards will use this GL context to render.

// [link]

var GL_PREINITIALIZED_CONTEXT = false;

// Enables building of stb-image, a tiny public-domain library for decoding

// images, allowing decoding of images without using the browser's built-in

// decoders. The benefit is that this can be done synchronously, however, it

// will not be as fast as the browser itself. When enabled, stb-image will be

// used automatically from IMG_Load and IMG_Load_RW. You can also call the

// ``stbi_*`` functions directly yourself.

// [link]

var STB_IMAGE = false;

// From Safari 8 (where WebGL was introduced to Safari) onwards, OES_texture_half_float and OES_texture_half_float_linear extensions

// are broken and do not function correctly, when used as source textures.

// See https://webkit.org/b/183321, https://webkit.org/b/169999,

// https://stackoverflow.com/questions/54248633/cannot-create-half-float-oes-texture-from-uint16array-on-ipad

// [link]

var GL_DISABLE_HALF_FLOAT_EXTENSION_IF_BROKEN = false;

// Workaround Safari WebGL issue: After successfully acquiring WebGL context on a canvas,

// calling .getContext() will always return that context independent of which 'webgl' or 'webgl2'

// context version was passed. See https://webkit.org/b/222758 and

// https://github.com/emscripten-core/emscripten/issues/13295.

// Set this to 0 to force-disable the workaround if you know the issue will not affect you.

// [link]

var GL_WORKAROUND_SAFARI_GETCONTEXT_BUG = true;

// If 1, link with support to glGetProcAddress() functionality.

// In WebGL, glGetProcAddress() causes a substantial code size and performance impact, since WebGL

// does not natively provide such functionality, and it must be emulated. Using glGetProcAddress()

// is not recommended. If you still need to use this, e.g. when porting an existing renderer,

// you can link with -sGL_ENABLE_GET_PROC_ADDRESS to get support for this functionality.

// [link]

var GL_ENABLE_GET_PROC_ADDRESS = true;

// Use JavaScript math functions like Math.tan. This saves code size as we can avoid shipping

// compiled musl code. However, it can be significantly slower as it calls out to JS. It

// also may give different results as JS math is specced somewhat differently than libc, and

// can also vary between browsers.

// [link]

var JS_MATH = false;

// Set this to enable compatibility emulations for old JavaScript engines. This gives you

// the highest possible probability of the code working everywhere, even in rare old

// browsers and shell environments. Specifically:

// - Disable WebAssembly. (Must be paired with -sWASM=0)

// - Adjusts MIN_X_VERSION settings to 0 to include support for all browser versions.

// - Avoid TypedArray.fill, if necessary, in zeroMemory utility function.

// You can also configure the above options individually.

// [link]

var LEGACY_VM_SUPPORT = false;

// Specify which runtime environments the JS output will be capable of running

// in. For maximum portability this can be configured to support all

// environments or it can be limited to reduce overall code size. The supported

// environments are:

// - 'web' - the normal web environment.

// - 'webview' - just like web, but in a webview like Cordova; considered to be

// same as "web" in almost every place

// - 'worker' - a web worker environment.

// - 'worklet' - Audio Worklet environment.

// - 'node' - Node.js.

// - 'shell' - a JS shell like d8, js, or jsc.

// This setting can be a comma-separated list of these environments, e.g.,

// "web,worker". If this is the empty string, then all environments are

// supported.

// Certain settings will automatically add to this list. For examble, building

// with pthreads will automatically add `worker` and building with

// ``AUDIO_WORKLET`` will automatically add `worklet`.

// Note that the set of environments recognized here is not identical to the

// ones we identify at runtime using ``ENVIRONMENT_IS_*``. Specifically:

// - We detect whether we are a pthread at runtime, but that's set for workers

// and not for the main file so it wouldn't make sense to specify here.

// - The webview target is basically a subset of web. It must be specified

// alongside web (e.g. "web,webview") and we only use it for code generation

// at compile time, there is no runtime behavior change.

// Note that by default we do not include the 'shell' environment since direct

// usage of d8, spidermonkey and jsc is extremely rare.

// [link]

var ENVIRONMENT = ['web', 'webview', 'worker', 'node'];

// Enable this to support lz4-compressed file packages. They are stored compressed in memory, and

// decompressed on the fly, avoiding storing the entire decompressed data in memory at once.

// If you run the file packager separately, you still need to build the main program with this flag,

// and also pass --lz4 to the file packager.

// (You can also manually compress one on the client, using LZ4.loadPackage(), but that is less

// recommended.)

// Limitations:

// - LZ4-compressed files are only decompressed when needed, so they are not available

// for special preloading operations like pre-decoding of images using browser codecs,

// preloadPlugin stuff, etc.

// - LZ4 files are read-only.

// [link]

var LZ4 = false;

// Emscripten (JavaScript-based) exception handling options.

// The three related settings (:ref:`DISABLE_EXCEPTION_CATCHING`,

// :ref:`EXCEPTION_CATCHING_ALLOWED`, and :ref:`DISABLE_EXCEPTION_THROWING`)

// only pertain to JavaScript-based exception handling and do not control the

// native Wasm exception handling option (``-fwasm-exceptions``)

// Disables generating code to actually catch exceptions. This disabling is on

// by default as the overhead of exceptions is quite high in size and speed

// currently (in the future, wasm should improve that). When exceptions are

// disabled, if an exception actually happens then it will not be caught

// and the program will halt (so this will not introduce silent failures).

// .. note::

// This removes *catching* of exceptions, which is the main

// issue for speed, but you should build source files with

// -fno-exceptions to really get rid of all exceptions code overhead,

// as it may contain thrown exceptions that are never caught (e.g.

// just using std::vector can have that). -fno-rtti may help as well.

// This option is mutually exclusive with :ref:`EXCEPTION_CATCHING_ALLOWED`.

// This option only applies to Emscripten (JavaScript-based) exception handling

// and does not control the native Wasm exception handling.

// [compile+link]

var DISABLE_EXCEPTION_CATCHING = 1;

// Enables catching exception but only in the listed functions. This

// option acts like a more precise version of ``DISABLE_EXCEPTION_CATCHING=0``.

// This option is mutually exclusive with :ref:`DISABLE_EXCEPTION_CATCHING`.

// This option only applies to Emscripten (JavaScript-based) exception handling

// and does not control the native Wasm exception handling.

// [compile+link]

var EXCEPTION_CATCHING_ALLOWED = [];

// Internal: Tracks whether Emscripten should link in exception throwing (C++

// 'throw') support library. This does not need to be set directly, but pass

// -fno-exceptions to the build disable exceptions support. (This is basically

// -fno-exceptions, but checked at final link time instead of individual .cpp

// file compile time) If the program *does* contain throwing code (some source

// files were not compiled with ``-fno-exceptions``), and this flag is set at link

// time, then you will get errors on undefined symbols, as the exception

// throwing code is not linked in. If so you should either unset the option (if

// you do want exceptions) or fix the compilation of the source files so that

// indeed no exceptions are used).

// This option only applies to Emscripten (JavaScript-based) exception handling

// and does not control the native Wasm exception handling.

// [compile+link]

var DISABLE_EXCEPTION_THROWING = false;

// Make the exception message printing function, 'getExceptionMessage' available

// in the JS library for use, by adding necessary symbols to

// :ref:`EXPORTED_FUNCTIONS`.

// This works with both Emscripten EH and Wasm EH. When you catch an exception

// from JS, that gives you a user-thrown value in case of Emscripten EH, and a

// WebAssembly.Exception object in case of Wasm EH. 'getExceptionMessage' takes

// the user-thrown value in case of Emscripten EH and the WebAssembly.Exception

// object in case of Wasm EH, meaning in both cases you can pass a caught

// exception directly to the function.

// When used with Wasm EH, this option additionally provides these functions in

// the JS library:

// - getCppExceptionTag: Returns the C++ tag

// - getCppExceptionThrownObjectFromWebAssemblyException:

// Given an WebAssembly.Exception object, returns the actual user-thrown C++

// object address in Wasm memory.

// Setting this option also adds refcount incrementing and decrementing

// functions ('incrementExceptionRefcount' and 'decrementExceptionRefcount') in

// the JS library because if you catch an exception from JS, you may need to

// manipulate the refcount manually to avoid memory leaks.

// See test_EXPORT_EXCEPTION_HANDLING_HELPERS in test/test_core.py for an

// example usage.

// [deprecated]

var EXPORT_EXCEPTION_HANDLING_HELPERS = false;

// When this is enabled, exceptions will contain stack traces and uncaught

// exceptions will display stack traces upon exiting. This defaults to true when

// ASSERTIONS is enabled. This option is for users who want exceptions' stack

// traces but do not want other overheads ASSERTIONS can incur.

// This option implies :ref:`EXPORT_EXCEPTION_HANDLING_HELPERS`.

// [link]

var EXCEPTION_STACK_TRACES = false;

// If true, emit instructions for the legacy Wasm exception handling proposal:

// https://github.com/WebAssembly/exception-handling/blob/main/proposals/exception-handling/legacy/Exceptions.md

// If false, emit instructions for the standardized exception handling proposal:

// https://github.com/WebAssembly/exception-handling/blob/main/proposals/exception-handling/Exceptions.md

// [compile+link]

var WASM_LEGACY_EXCEPTIONS = true;

// Whether to support async operations in the compiled code. This makes it

// possible to call JS functions from synchronous-looking code in C/C++.

// - 1 (default): Run binaryen's Asyncify pass to transform the code using

// asyncify. This emits a normal wasm file in the end, so it works everywhere,

// but it has a significant cost in terms of code size and speed.

// See https://emscripten.org/docs/porting/asyncify.html

// - 2 (deprecated): Use ``-sJSPI`` instead.

// [link]

var ASYNCIFY = 0;

// Imports which can do an async operation, in addition to the default ones that

// emscripten defines like emscripten_sleep. If you add more you will need to

// mention them to here, or else they will not work (in :ref:`ASSERTIONS` builds

// an error will be shown).

// Note that this list used to contain the default ones, which meant that you

// had to list them when adding your own; the default ones are now added

// automatically.

// [link]

var ASYNCIFY_IMPORTS = [];

// Whether indirect calls can be on the stack during an unwind/rewind.

// If you know they cannot, then setting this can be extremely helpful, as

// otherwise asyncify must assume an indirect call can reach almost everywhere.

// [link]

var ASYNCIFY_IGNORE_INDIRECT = false;

// The size of the asyncify stack - the region used to store unwind/rewind

// info. This must be large enough to store the call stack and locals. If it is

// too small, you will see a wasm trap due to executing an "unreachable"

// instruction. In that case, you should increase this size.

// [link]

var ASYNCIFY_STACK_SIZE = 4096;

// If the Asyncify remove-list is provided, then the functions in it will not

// be instrumented even if it looks like they need to. This can be useful

// if you know things the whole-program analysis doesn't, like if you

// know certain indirect calls are safe and won't unwind. But if you

// get the list wrong things will break (and in a production build user

// input might reach code paths you missed during testing, so it's hard

// to know you got this right), so this is not recommended unless you

// really know what are doing, and need to optimize every bit of speed

// and size.

// The names in this list are names from the WebAssembly Names section. The

// wasm backend will emit those names in *human-readable* form instead of

// typical C++ mangling. For example, you should write ``Struct::func()``

// instead of ``_ZN6Struct4FuncEv``. C is also different from C++, as C

// names don't end with parameters; as a result foo(int) in C++ would appear

// as just foo in C (C++ has parameters because it needs to differentiate

// overloaded functions). You will see warnings in the console if a name in the

// list is missing (these are not errors because inlining etc. may cause

// changes which would mean a single list couldn't work for both -O0 and -O1

// builds, etc.). You can inspect the wasm binary to look for the actual names,

// either directly or using wasm-objdump or wasm-dis, etc.

// Simple ``*`` wildcard matching is supported.

// To avoid dealing with limitations in operating system shells or build system

// escaping, the following substitutions can be made:

// - ' ' -> ``.``,

// - ``&`` -> ``#``,

// - ``,`` -> ``?``.

// That is, the function `"foo(char const*, int&)"` can be inputted as

// `"foo(char.const*?.int#)"` on the command line instead.

// Note: Whitespace is part of the function signature! I.e.

// "foo(char const *, int &)" will not match "foo(char const*, int&)", and

// neither would "foo(const char*, int &)".

// [link]

var ASYNCIFY_REMOVE = [];

// Functions in the Asyncify add-list are added to the list of instrumented

// functions, that is, they will be instrumented even if otherwise asyncify

// thinks they don't need to be. As by default everything will be instrumented

// in the safest way possible, this is only useful if you use IGNORE_INDIRECT

// and use this list to fix up some indirect calls that *do* need to be

// instrumented.

// See :ref:`ASYNCIFY_REMOVE` about the names, including wildcard matching and

// character substitutions.

// [link]

var ASYNCIFY_ADD = [];

// If enabled, instrumentation status will be propagated from the add-list, ie.

// their callers, and their callers' callers, and so on. If disabled then all

// callers must be manually added to the add-list (like the only-list).

// [link]

var ASYNCIFY_PROPAGATE_ADD = true;

// If the Asyncify only-list is provided, then *only* the functions in the list

// will be instrumented. Like the remove-list, getting this wrong will break

// your application.

// See :ref:`ASYNCIFY_REMOVE` about the names, including wildcard matching and

// character substitutions.

// [link]

var ASYNCIFY_ONLY = [];

// If enabled will output which functions have been instrumented and why.

// [link]

var ASYNCIFY_ADVISE = false;

// Runtime debug logging from asyncify internals.

// - 1: Minimal logging.

// - 2: Verbose logging.

// [link]

var ASYNCIFY_DEBUG = 0;

// Deprecated, use JSPI_EXPORTS instead.

// [deprecated]

var ASYNCIFY_EXPORTS = [];

// Use VM support for the JavaScript Promise Integration proposal. This allows

// async operations to happen without the overhead of modifying the wasm.

// See https://github.com/WebAssembly/js-promise-integration/

// TODO: document which of the following flags are still relevant in this mode

// (e.g. IGNORE_INDIRECT etc. are not needed)

// [link]

var JSPI = 0;

// A list of exported module functions that will be asynchronous. Each export

// will return a ``Promise`` that will be resolved with the result. Any exports

// that will call an asynchronous import (listed in ``JSPI_IMPORTS``) must be

// included here.

// By default this includes ``main``.

// [link]

var JSPI_EXPORTS = [];

// A list of imported module functions that will potentially do asynchronous

// work. The imported function should return a ``Promise`` when doing

// asynchronous work.

// Note when using JS library files, the function can be marked with

// ``<function_name>_async:: true`` in the library instead of this setting.

// [link]

var JSPI_IMPORTS = [];

// Runtime elements that are exported on Module by default. We used to export

// quite a lot here, but have removed them all. You should use

// EXPORTED_RUNTIME_METHODS for things you want to export from the runtime.

// Note that the name may be slightly misleading, as this is for any JS library

// element, and not just methods. For example, we can export the FS object by

// having "FS" in this list.

// [link]

var EXPORTED_RUNTIME_METHODS = [];

// A list of incoming values on the Module object in JS that we care about. If

// a value is not in this list, then we don't emit code to check if you provide

// it on the Module object. For example, if

// you have this::

// var Module = {

// print: (x) => console.log('print: ' + x),

// preRun: [() => console.log('pre run')]

// };

// Then INCOMING_MODULE_JS_API must contain 'print' and 'preRun'; if it does not

// then we may not emit code to read and use that value. In other words, this

// option lets you set, statically at compile time, the list of which Module

// JS values you will be providing at runtime, so the compiler can better

// optimize.

// Setting this list to [], or at least a short and concise set of names you

// actually use, can be very useful for reducing code size. By default, the

// list contains a set of commonly used symbols.

// In addition to the default symbols, the following are also available:

// - fetchSettings

// - logReadFiles

// - loadSplitModule

// - onMalloc

// - onRealloc

// - onFree

// - onSbrkGrow

// - onCOSCacheHit

// - onCOSCacheMiss

// - onCOSStore

// - GL_MAX_TEXTURE_IMAGE_UNITS

// - SDL_canPlayWithWebAudio

// - SDL_numSimultaneouslyQueuedBuffers

// - freePreloadedMediaOnUse

// - preinitializedWebGLContext

// - keyboardListeningElement

// - doNotCaptureKeyboard

// - extraStackTrace

// - preloadPlugins

// - preMainLoop

// - postMainLoop

// - forcedAspectRatio

View remainder of file in raw view

emscripten/src/settings.js at main · emscripten-core/emscripten · GitHub

Uh oh!

Expand file tree

Breadcrumbs

settings.js

Latest commit

History

Breadcrumbs

settings.js

File metadata and controls