Cross-compiling

   1 Cross-compiling NetHack 3.7 Last edit: February 18, 2023
   2
   3 The NetHack 3.7 build process differs from the build process of previous
   4 versions in some important ways. Those differences make it possible to use
   5 a cross-compiler running on one platform (the "host" platform of the build)
   6 to produce a binary NetHack package that can execute on an entirely different
   7 platform.
   8
   9 Part A Contents:
  10     A1. Why cross-compile?
  11     A2. Building NetHack 3.6 (before)
  12     A3. Building NetHack 3.7 (going forward)
  13     A4. How was the build procedure reduced to 5 steps?
  14     A5. How can I help with the cross-compiling initiative?
  15
  16 Part B Contents:
  17     B1. Two sets of compiles and procedures
  18     B2. What needs to be built and executed on the HOST?
  19     B3. What needs to be built for the TARGET?
  20     B4. Case sample: msdos
  21     B5. Case sample: amiga (started but incomplete)
  22     B6. Case sample: Web Assembly, libnh
  23
  24 --------------------------------------------------------------------------------
  25  Part A - Cross-compiling NetHack
  26 --------------------------------------------------------------------------------
  27
  28   +--------------------------+
  29   | A1. Why cross-compile?   |
  30   +--------------------------+
  31
  32 By using cross-compilers on host platforms with fast processors, plenty of RAM
  33 and storage resources, and an available cross-compiler, it may be possible to
  34 keep or resurrect a working version of NetHack on platforms that are now too
  35 constrained to carry out the build process natively on the platform anymore.
  36
  37 Some of the constraints in carrying out a native build on the desired target
  38 may include, but not necessarily be limited to, any of the following:
  39
  40   o Access: Somebody with a working knowledge of the NetHack build process may
  41     not have the desired target build platform available to them. Conversely,
  42     somebody with a keen knowledge of the target platform, and access to it,
  43     may not be all that familiar with the NetHack build process.
  44
  45   o Resources: Address space limitations, insufficient RAM, low amounts of disk
  46     storage, slow processor performance, may impede the ability to execute the
  47     compile process on the target platform.
  48
  49   o Compilers: Some of the native compilers on historical platforms may only
  50     support the dialect of C that was popular when the platform and compiler
  51     were in their prime.
  52
  53 Another useful potential result of cross-compiling, is that it paves the way
  54 for carrying out test and production builds of NetHack for multiple target
  55 platforms through automated steps carried out on the host platform(s).
  56
  57
  58   +-------------------------------------+
  59   | A2. Building NetHack 3.6 (before)   |
  60   +-------------------------------------+
  61
  62 Very generally, the build of NetHack in past versions required the following
  63 steps to be carried out:
  64
  65     1. Compile and link util/makedefs.
  66     2. Run makedefs repeatedly with different command line options to produce
  67        several output files that are required for:
  68         (a) additional build steps to follow, including some header
  69             files: pm.h, onames.h, date.h.
  70         (b) creation of files, containing information required by,
  71             or about the game during its execution, that are stored in a
  72             portable, platform-independent way, that need to be inserted
  73             into the game package.
  74         (c) creation of files containing information required by, or about
  75             the game during its execution, that are stored in an architecture
  76             and/or platform and/or operating system dependent way, that need
  77             to be inserted into the game package (the quest text format is
  78             one example).
  79     3. Compile and link the level compiler. This step needs to execute
  80        work-alike tools to lex and yacc, or needs to build pre-built lex and
  81        yacc output (.c, .h files) that are provided in the sys/share part of
  82        the NetHack source code tree.
  83     4. Execute the level compiler to read dat/*.des files and create
  84        a set of binary output files that are architecture and/or operating
  85        system dependent on the build platform, for use by the game during
  86        its execution.
  87     5. Compile and link the dungeon compiler. Like the level compiler, this
  88        step needs to execute work-alike tools to lex and yacc, or needs to
  89        build pre-built lex and yacc output (.c, .h files) that are provided
  90        in the sys/share part of the NetHack source code tree.
  91     6. Execute the dungeon compiler to read dat/dungeon.def and create
  92        a set of binary output files that are architecture and/or operating
  93        system dependent on the build platform, for use by the game during
  94        its execution.
  95     7. Compile and link several less critical utilities such as uudecode,
  96        tile-generation utilities, and so forth, all of which need to execute
  97        on the build platform during the build process to produce output files
  98        for use during the game, that are reasonably portable (not architecture
  99        and/or operating system dependent; only the output of the utilities
 100        becomes part of the game package, not the executable utilities
 101        themselves.
 102     8. Compile and link the game itself.
 103     9. Package the game and its required files including the output from
 104        previous steps 2b, 2c, 4, 6, 7 and 8 above.
 105
 106 Steps 1, 2a, 2b, 7, and 9 above are not impediments to cross-compiling NetHack.
 107
 108 Steps 2c, 3, 4, 5, 6 and 8 above are impediments to cross-compiling NetHack.
 109
 110 That's because the files that those steps produce are very much tied to the
 111 platform where the build of NetHack is being carried out. Variations between
 112 platforms (such as 32-bit vs 64-bit, integer sizes, pointer sizes, processor
 113 byte order, data alignment requirements, struct padding and the way bitfields
 114 are stored) impact the portability of those data files between different
 115 platforms and operating systems. If all those things happen to match, the files
 116 might, just might, be usable across platforms, but the chances are against it,
 117 and that certainly cannot be counted on.
 118
 119   +------------------------------------------+
 120   | A3. Building NetHack 3.7 (going forward) |
 121   +------------------------------------------+
 122
 123 Again, very generally, the build of NetHack in 3.7 requires the following
 124 steps to be carried out:
 125
 126     1. Compile and link util/makedefs.
 127     2. Run makedefs repeatedly with different command line options to produce
 128        several required output files that contain information required by the
 129        game, or contain information about the game during its execution, that
 130        are stored in a portable, platform-independent way, that need to be
 131        inserted into the game package (makedefs -d, -o, -r, -h, -s).
 132     3. Compile and link several less critical utilities such as uudecode,
 133        tile-generation utilities, and so forth, all of which need to execute
 134        on the build platform during the build process to produce output files
 135        for use during the game, that are reasonably portable (not architecture
 136        and/or operating system dependent; only the output of the utilities
 137        becomes part of the game package, not the executable utilities
 138        themselves.
 139     4. Compile and link the game components for the TARGET; that includes
 140        NetHack itself, Lua, and any optional regular-expression or window port
 141        libraries that you plan to link into the NetHack game executable.
 142     5. Package the game and its required files including the output from
 143        previous steps 2, 3 and 4 above.
 144
 145 Step 4 is now the only impediment to cross-compiling NetHack. That impediment
 146 is resolved by executing step 4 using a cross-compiler that runs on the build (host)
 147 platform to produce a resulting binary for the target platform, instead of
 148 executing the native compiler.
 149
 150   +-----------------------------------------------------+
 151   | A4. How was the build procedure reduced to 5 steps? |
 152   +-----------------------------------------------------+
 153
 154 The following are among several design changes planned in NetHack 3.7,
 155 and these specific changes are what altered the build process to make
 156 cross-compiling possible:
 157
 158     o  There is no creation of platform-dependent files, such as the quest
 159        text files, by makedefs during the build process. Instead, the quest
 160        text files have been converted to Lua and are inserted into the game
 161        package for processing by the embedded Lua during execution of NetHack.
 162
 163     o  There is no build-time level compiler involved. Instead, the level
 164        descriptions have been converted to Lua and are inserted into the game
 165        package for processing by the embedded Lua during execution of NetHack.
 166
 167     o  There is no build-time dungeon compiler involved. Instead, the dungeon
 168        description has been converted to Lua and is inserted into the game
 169        package for processing by the embedded Lua during execution of NetHack.
 170
 171     o  Some of the build and option information that was formerly produced
 172        during build time by makedefs, and contained information about the
 173        build-platform specifically, is now produced at runtime within the
 174        game under a cross-compiled build. As such, it now produces information
 175        applicable to the target NetHack environment, not the build environment.
 176
 177   +------------------------------------------------------------+
 178   | A5. How can I help with the cross-compiling initiative?    |
 179   +------------------------------------------------------------+
 180
 181     o  If you have a favourite target platform (let's call it XX-Platform for
 182        example purposes) that you'd like to see NetHack be able to run on, do
 183        some research to find out if a cross-compiler exists that:
 184            - produces output for XX-Platform.
 185            - executes on a platform that you use and love (Linux, Windows,
 186              macOS are some examples of platforms that have cross-compilers
 187              for other targets available)
 188
 189     o  Then, make the community, devteam, and others aware that you're starting
 190        a cross-compile of NetHack for XX-Platform. You might need to ask some
 191        "starting out" questions initially, and as you get deeper into it, you
 192        might need to ask some tougher questions.
 193
 194     o  Perhaps consider forking from NetHack on GitHub, and do the
 195        cross-compiler work there in your fork. Strive to get it to a point where
 196        it's ready to play-test on XX-Platform, or perhaps even use an emulator
 197        of XX-Platform if one is available. We live in a time where plenty do.
 198
 199        Doing your work on a GitHub fork has the following advantages:
 200            - It will make it really simple to integrate your work back into
 201              the NetHack source tree if that's one of your goals.
 202            - It will make it possible and straightforward to merge upstream
 203              NetHack changes into your work for the XX-Platform cross-compile
 204              so that it stays current with the game as it evolves.
 205            - You may get help from others in the form of suggestions, or
 206              pull-requests, or offers to join the development. Chances are,
 207              you aren't the only person out there that would like to
 208              establish/resurrect/maintain NetHack on XX-Platform.
 209
 210        Have fun!
 211
 212 -----------------------------------------------------------------------------
 213  Part B - Cross-compiling details
 214 -----------------------------------------------------------------------------
 215
 216 Part B Contents:
 217     B1. Two sets of compiles and procedures
 218     B2. What needs to be built and executed on the HOST?
 219     B3. What needs to be built for the TARGET?
 220     B4. Case sample: msdos
 221
 222   +-----------------------------------------+
 223   | B1. Two sets of compiles and procedures |
 224   +-----------------------------------------+
 225
 226 The HOST is the platform/place that you're running the build procedures using
 227 the native compiler/linker, and the cross-compiler/linker that runs on the HOST
 228 to build the game for a TARGET platform.
 229
 230 You have to:
 231     1. Build mandatory utilities on the HOST.
 232     2. Execute the mandatory utilities to generate components that will be used
 233        during step 4 to build the game itself, or that will generate components
 234        that will become part of the TARGET game package.
 235     3. Build optional or enhancing utilities on the HOST, execute those
 236        optional or enhancing utilities on the HOST to generate components that
 237        will become part of the TARGET game package.
 238     4. Execute a supported cross-compiler to compile the rest of the game
 239        components like NetHack, Lua, and any optional libraries (the word
 240        "supported", in this sense, means a compiler that runs on your HOST
 241        build platform, and generates output executable files for the TARGET
 242        platform).
 243
 244 It should be mentioned that you can execute the cross-compile build approach
 245 to generate binaries for the same platform as the host, where the HOST
 246 compiler and the TARGET compiler are the same.
 247
 248
 249   +------------------------------------------------------+
 250   | B2. What needs to be built and executed on the HOST? |
 251   +------------------------------------------------------+
 252
 253 On the HOST, here are the mandatory things that have to be built.
 254
 255     a) Using the HOST native compiler, build  HOST native utility makedefs
 256
 257        Compile and link the following with these compiler switches:
 258          -DCROSSCOMPILE
 259        from sources: util/makedefs.c, src/mdlib.c, src/monst.c, src/objects.c
 260                      src/date.c, src/alloc.c
 261
 262     b) Execute HOST native makedefs utility, util/makedefs, as follows:
 263           Required for complete packaging of the game, but not the C source
 264           game compile:
 265               util/makedefs -d
 266               util/makedefs -r
 267               util/makedefs -h
 268               util/makedefs -s
 269
 270     c) Using the HOST native compiler, build these additional utilities if your
 271        target platform requires components that they produce. It is important
 272        to note that all of the required source files need to be compiled to
 273        native obj files for linking into the HOST-side utility. Some of the
 274        source files (src/monst.c, src/objects.c) were likely already compiled
 275        as native HOST-side obj files in order to build the native HOST utility
 276        'makedefs' HOST utility above, and you don't need to compile them again
 277        for use in linking other HOST utilities if the HOST-native obj files
 278        produced from them are still around.
 279
 280        NOTE: There are some source files that need to be compiled for linking
 281        into utilities that are needed on the HOST side, but that are also
 282        needed again later as TARGET obj files for linking into the TARGET
 283        executable, and therefore must be compiled twice.
 284        They include: src/drawing.c, src/objects.c, src/monst.c,
 285        src/alloc.c, util/panic.c. It is important to keep the compiled
 286        HOST-side obj files produced by the HOST native compiler distinct from
 287        the TARGET-side obj files produced by the cross-compiler. That can be
 288        accomplished either by naming the generated object files a little
 289        differently (perhaps with a suffix) between the HOST-side and the
 290        TARGET-side, or by placing the HOST-side obj files and the TARGET-side
 291        obj files into distinct, different directories during the build process.
 292        Use whatever method works best for your cross-compile effort and tools.
 293
 294           util/dlb
 295
 296                    from sources: src/dlb.c, src/dlb_main.c, src/alloc.c,
 297                                  util/panic.c
 298                    purpose:      For packaging up many files that are
 299                                  required components of the TARGET game
 300                                  into a single nhdat or nhdat370 combined
 301                                  file
 302
 303           util/uudecode
 304
 305                    from sources: sys/share/uudecode.c
 306                    purpose:      convert some binary files, that are
 307                                  distributed in the NetHack sources in
 308                                  uuencoded format, back into their
 309                                  original binary state
 310           util/tilemap
 311
 312                    from sources: win/share/tilemap.c
 313                    purpose:      produce output file src/tile.c that is
 314                                  required for building TARGET packages with
 315                                  tile support
 316
 317           util/tile2bmp
 318
 319                    from sources: win/share/tile2bmp.c, win/share/tiletext.c,
 320                                  win/share/tilemap.c, src/drawing.c,
 321                                  src/monst.c, src/objects.c
 322                    purpose:      Read win/share/monsters.txt,
 323                                  win/share/objects.txt and win/share/other.txt
 324                                  files and produce a .bmp file.
 325
 326           util/gif2txt
 327
 328                    from sources: win/share/gifread.c, win/share/tiletext.c,
 329                                  win/share/tilemap.c, src/drawing.c,
 330                                  src/monst.c, src/objects.c,
 331                                  src/alloc.c, util/panic.c
 332                    purpose:      Read win/share/monsters.txt,
 333                                  win/share/objects.txt and win/share/other.txt
 334                                  files and produce a .gif file.
 335
 336           util/ppmwrite
 337
 338                    from sources: win/share/ppmwrite.c, win/share/tiletext.c,
 339                                  win/share/tilemap.c, src/drawing.c,
 340                                  src/monst.c, src/objects.c,
 341                                  src/alloc.c, util/panic.c
 342                    purpose:      Read win/share/monsters.txt,
 343                                  win/share/objects.txt and win/share/other.txt
 344                                  files and produce a .ppm file.
 345
 346
 347   +--------------------------------------------+
 348   | B3. What needs to be built for the TARGET? |
 349   +--------------------------------------------+
 350
 351
 352 For the TARGET side, here are the mandatory things that have to be built via
 353 the HOST-executed cross-compiler that generates code for the TARGET platform.
 354
 355 Using the cross-compiler, build the following targets:
 356
 357     a) NetHack sources (core is mandatory)
 358
 359        With the cross-compiler and linker for the TARGET platform,
 360        cross-compile and link with these compiler switches:
 361          -DCROSSCOMPILE and -DCROSSCOMPILE_TARGET
 362
 363        core sources (2019): src/allmain.c, src/alloc.c, src/apply.c,
 364                            src/artifact.c, src/attrib.c, src/ball.c,
 365                            src/bones.c, src/botl.c, src/cmd.c, src/dbridge.c,
 366                            src/decl.c, src/detect.c, src/dig.c, src/display.c,
 367                            src/dlb.c, src/do.c, src/do_name.c, src/do_wear.c,
 368                            src/dog.c, src/dogmove.c, src/dokick.c,
 369                            src/dothrow.c, src/drawing.c, src/dungeon.c,
 370                            src/eat.c, src/end.c, src/engrave.c, src/exper.c,
 371                            src/explode.c, src/extralev.c, src/files.c,
 372                            src/fountain.c, src/hack.c, src/hacklib.c,
 373                            src/insight.c, src/invent.c, src/isaac64.c,
 374                            src/light.c, src/lock.c, src/mail.c,
 375                            src/makemon.c, src/mcastu.c,
 376                            src/mdlib.c, src/mhitm.c, src/mhitu.c, src/minion.c,
 377                            src/mklev.c, src/mkmap.c, src/mkmaze.c, src/mkobj.c,
 378                            src/mkroom.c, src/mon.c, src/mondata.c,
 379                            src/monmove.c, src/monst.c, src/mplayer.c,
 380                            src/mthrowu.c, src/muse.c, src/music.c,
 381                            src/nhlsel.c, src/nhlua.c, src/nhlobj.c,
 382                            src/o_init.c, src/objects.c, src/objnam.c,
 383                            src/options.c, src/pager.c, src/pickup.c,
 384                            src/pline.c, src/polyself.c, src/potion.c,
 385                            src/pray.c, src/priest.c, src/quest.c,
 386                            src/questpgr.c, src/read.c, src/rect.c,
 387                            src/region.c, src/restore.c, src/rip.c, src/rnd.c,
 388                            src/role.c, src/rumors.c, src/save.c, src/sfstruct.c,
 389                            src/shk.c, src/shknam.c, src/sit.c, src/sounds.c,
 390                            src/sp_lev.c, src/spell.c, src/steal.c, src/steed.c,
 391                            src/symbols.c, src/sys.c, src/teleport.c,
 392                            src/timeout.c, src/topten.c, src/track.c,
 393                            src/trap.c, src/u_init.c, src/uhitm.c, src/vault.c,
 394                            src/version.c, src/vision.c,
 395                            src/weapon.c, src/were.c, src/wield.c, src/windows.c,
 396                            src/wizard.c, src/worm.c, src/worn.c, src/write.c,
 397                            src/zap.c, sys/share/cppregex.cpp
 398
 399        tty sources:        win/tty/getline.c, win/tty/termcap.c,
 400                            win/tty/topl.c, win/tty/wintty.c
 401
 402        generated (if req'd):
 403                           src/tile.c
 404
 405        plus your platform-specific source files that contain main, typically
 406        *main.c, and unix support in *unix.c, tty support in *tty.c, and other
 407        system support in *sys.c as well as others sources pertaining to your
 408        specific target platform(s).
 409
 410     b) Lua (mandatory in 3.7)
 411
 412           lib/lua-5.4.6/src
 413
 414                    from sources: lua.c, lapi.c, lauxlib.c, lbaselib.c, lcode.c,
 415                                  lcorolib.c, lctype.c, ldblib.c, ldebug.c,
 416                                  ldo.c, ldump.c, lfunc.c, lgc.c, linit.c,
 417                                  liolib.c, llex.c, lmathlib.c, lmem.c,
 418                                  loadlib.c, lobject.c, lopcodes.c,
 419                                  loslib.c, lparser.c, lstate.c, lstring.c,
 420                                  lstrlib.c, ltable.c, ltablib.c, ltm.c,
 421                                  lundump.c, lutf8lib.c, lvm.c, lzio.c,
 422                                  lbitlib.c
 423                    purpose:      links into the game executable to interpret
 424                                  lua level description files, lua dungeon
 425                                  description files, and a lua quest text file.
 426
 427     d) recover (optional if desired/required; some targets have recover
 428        functionality built into NetHack itself)
 429
 430     c) Additional optional library packages/obj files as required
 431
 432           lib/pdcurses/...
 433           or lib/pdcursesmod/...
 434
 435                    from sources: addch.c, addchstr.c, addstr.c, attr.c, beep.c,
 436                                  bkgd.c, border.c, clear.c, color.c, delch.c,
 437                                  deleteln.c, getch.c, getstr.c, getyx.c,
 438                                  inch.c, inchstr.c, initscr.c, inopts.c,
 439                                  insch.c, insstr.c, instr.c, kernel.c,
 440                                  keyname.c, mouse.c, move.c, outopts.c,
 441                                  overlay.c, pad.c, panel.c, printw.c,
 442                                  refresh.c, scanw.c, scr_dump.c, scroll.c,
 443                                  slk.c, termattr.c, touch.c, util.c, window.c,
 444                                  debug.c, pdcclip.c, pdcdisp.c, pdcgetsc.c,
 445                                  pdckbd.c, pdcutil.c
 446                    purpose:      underlying curses platform support for some
 447                                  target platforms where inclusion of the
 448                                  NetHack curses window port in win/curses is
 449                                  desired
 450
 451   +-------------------------+
 452   | B4. Case sample: msdos  |
 453   +-------------------------+
 454
 455 Cross-compiler used:     Andrew Wu's djgpp cross-compiler
 456 Cross-compiler url:      https://github.com/andrewwutw/build-djgpp
 457 Cross-compiler pre-built binary downloads:
 458     https://github.com/andrewwutw/build-djgpp/releases
 459
 460     Cross-compiler bits tested:
 461            https://github.com/andrewwutw/build-djgpp
 462        and the pre-built binary for your platform from:
 463            https://github.com/andrewwutw/build-djgpp/releases
 464        and a DOS-extender (for including in msdos packaging) from
 465            http://sandmann.dotster.com/cwsdpmi/csdpmi7b.zip
 466        and pdcurses from:
 467            https://github.com/wmcbrine/PDCurses.git
 468        or pdcursesmod from:
 469            https://github.com/Bill-Gray/PDCursesMod.git
 470
 471     - A shell script to download that djgpp cross-compiler and associated
 472       pieces for either linux or macOS is available:
 473
 474            sh sys/msdos/fetch-cross-compiler.sh
 475
 476     That script won't install anything, it just does file fetches and stores
 477     them in subfolders of lib. The linux.370 and macOS.370 hints files are
 478     configured to find the cross-compiler there if you add
 479         CROSS_TO_MSDOS=1
 480     on your make command line.
 481
 482     Note: Both the fetch-cross-compiler.sh script and and the msdos
 483     cross-compile and package procedures require unzip and zip to be available
 484     on your host build system.
 485
 486     On your linux host:
 487
 488         cd sys/unix ; sh setup.sh hints/linux.370 ; cd ../..
 489         make fetch-lua
 490
 491     On your macOS host:
 492
 493         cd sys/unix ; sh setup.sh hints/macOS.370 ; cd ../..
 494         make fetch-lua
 495
 496     The MSDOS cross-compile can then be carried out by specifying
 497     CROSS_TO_MSDOS=1 on the make command line:
 498
 499         make CROSS_TO_MSDOS=1 all
 500         make CROSS_TO_MSDOS=1 package
 501
 502     You can explicitly include tty and curses support if desired. The default
 503     you'll end up with is a tty-only cross-compile build:
 504
 505         make WANT_WIN_TTY=1 WANT_WIN_CURSES=1 CROSS_TO_MSDOS=1 package
 506
 507     Result: The "make package" target will bundle all of the necessary
 508             components to run NetHack on msdos into a folder:
 509                 targets/msdos/pkg
 510             and then it zips the contents of that folder into:
 511                 targets/msdos/nh370dos.zip
 512
 513     Also note that building the msdos targets using the make command
 514     above, does not preclude you from building local linux or macOS
 515     targets as well. Just drop the CROSS_TO_MSDOS=1 from the make
 516     command line. That's because the cross-compiler hints additions are
 517     enclosed inside ifdef sections and won't interfere with the
 518     non-cross-compile build in that case.
 519
 520   +-------------------------+
 521   | B5. Case sample: amiga  |
 522   +-------------------------+
 523
 524 Disclaimer: This is a minimal recipe, just to help someone else get
 525             started if they have a desire to get a full cross-compile of
 526             NetHack going for the Amiga.
 527             See CAVEATS below.
 528
 529 Cross-compiler used:     bebbo's amiga-gcc
 530 Cross-compiler url:      https://github.com/bebbo/amiga-gcc
 531
 532     To our knowledge, a pre-built copy of the cross-compiler isn't available,
 533     so you will likely have to obtain the cross-compiler sources via git and
 534     build it on your system.
 535
 536     The build prerequisite packages for building the compiler on Ubuntu can be
 537     easily obtained:
 538
 539         sudo apt install make wget git gcc g++ lhasa libgmp-dev \
 540             libmpfr-dev libmpc-dev flex bison gettext texinfo ncurses-dev \
 541             autoconf rsync
 542
 543     The build prerequisite packages for macOS via homebrew are documented but
 544     not tested by us any of us to date.
 545
 546         brew install bash wget make lhasa gmp mpfr libmpc flex gettext \
 547         texinfo gcc make autoconf
 548
 549     After installing the prerequite packages and the cross-compiler
 550     it was a straightforward build:
 551
 552             git clone https://github.com/bebbo/amiga-gcc.git
 553             cd amiga-gcc
 554             make update
 555
 556            [Note that you may have to take ownership of the files in the bebbo
 557             repo via chown before succesfully carrying out the next steps]
 558
 559             make clean
 560             make clean-prefix
 561             date; make all -j3 >&b.log; date
 562
 563     The compiler pieces are installed in /opt/amiga by default. If you prefer,
 564     you can alter the prefix before you build if you want. The instructions
 565     for doing so were spelled out at the time of this writing at:
 566
 567         https://github.com/bebbo/amiga-gcc
 568
 569     On your linux host:
 570
 571         cd sys/unix ; sh setup.sh hints/linux.370 ; cd ../..
 572         make fetch-lua
 573
 574     On your macOS host:
 575
 576         cd sys/unix ; sh setup.sh hints/macOS.370 ; cd ../..
 577         make fetch-lua
 578
 579     The Amiga cross-compile can then be carried out by specifying
 580     CROSS_TO_AMIGA=1 on the make command line:
 581
 582         make CROSS_TO_AMIGA=1 all
 583         make CROSS_TO_AMIGA=1 package
 584
 585     You can explicitly include tty and curses support if desired, otherwise
 586     you'll end up with a tty-only cross-compile build. The SDL1 pdcurses
 587     support has not been tested.
 588
 589         make WANT_WIN_TTY=1 WANT_WIN_CURSES=1 CROSS_TO_AMIGA=1 all
 590
 591     Result: The "make package" target will bundle the (hopefully) necessary
 592             components to run NetHack on msdos into a folder:
 593                 targets/amiga/pkg
 594             and then it zips the contents of that folder into:
 595                 targets/amiga/nh370ami.zip
 596
 597     Also note that building the amiga targets using the make command
 598     above, does not preclude you from building local linux or macOS
 599     targets as well. Just drop the CROSS_TO_AMIGA=1 from the make
 600     command line.
 601
 602     The cross-compiler hints additions are enclosed inside ifdef sections
 603     and won't interfere with the non-cross-compile build in that case.
 604
 605     CAVEATS: The original NetHack Amiga build steps included the source for
 606              some utilities that were built and executed on the amiga:
 607                  txt2iff and xpm2iff
 608              as part of the NetHack build procedure on amiga.
 609              Those did not compile out-of-the-box on the linux host. They
 610              will either have to be:
 611              - ported to build and run on the linux or macOS cross-compile
 612                host
 613           or
 614
 615              - their functionality will have to be rolled into amiga NetHack
 616                itself and executed on the target Amiga the first time the game
 617                is run, perhaps.
 618
 619     If you make headway, or are successful getting a working copy of
 620     NetHack going on the amiga, drop us a note at devteam@nethack.org.
 621
 622   +--------------------------------+
 623   | B6. Case sample: Web Assembly  |
 624   +--------------------------------+
 625
 626 Credit: The initial Web Assembly cross compile was found in a pull request:
 627             https://github.com/NetHack/NetHack/pull/385
 628         by apowers313. The pull request was merged with some accompanying
 629         NetHack source tree integration changes in early October 2020.
 630
 631 Cross-compiler used: emscripten
 632 Cross-compiler url: https://emscripten.org/docs/getting_started/downloads.html
 633
 634     Here's a brief guide to obtaining the cross-compiler sources via git and
 635     building it on your system.
 636
 637     For Ubuntu, the build prerequisite packages for building the compiler can
 638     be easily obtained:
 639
 640         sudo apt-get install python3 cmake default-jre
 641
 642     For macOS, you will need to install Xcode, git, cmake, Python 3.5 or new
 643     (at time of this writing).
 644
 645     After installing the prerequite packages above, obtain the cross-compiler
 646     via git and build it from the directory of your choice using steps similar
 647     to these:
 648
 649             git clone https://github.com/emscripten-core/emsdk.git
 650             cd emsdk
 651             git pull
 652             ./emsdk install latest
 653             ./emsdk activate latest
 654             source ./emsdk_env.sh
 655
 656     The steps above reflect what was outlined at this url at the time
 657     of writing:
 658
 659             https://emscripten.org/docs/getting_started/downloads.html
 660
 661     That is the definitive source and trumps anything documented here.
 662
 663     On your linux host, prepare to cross-compile NetHack as follows:
 664
 665         cd sys/unix ; sh setup.sh hints/linux.370 ; cd ../..
 666         make fetch-lua
 667
 668     On your macOS host, prepare to cross-compile NetHack as follows:
 669
 670         cd sys/unix ; sh setup.sh hints/macOS.370 ; cd ../..
 671         make fetch-lua
 672
 673     Then, cross-compile to targets/wasm as follows:
 674
 675         make CROSS_TO_WASM=1
 676
 677     You can build src/libnh.a from pull request 385 as follows:
 678
 679         make WANT_LIBNH=1
 680
 681     Do not add any additional windowport interfaces to your build
 682     (such as WANT_WIN_TTY=1 WANT_WIN_CURSES=1 WANT_WIN_X11=1 or
 683     WANT_WIN_QT=1) as those aren't applicable to the Web Assembly
 684     or nethacklib builds. A "shim" pseudo-windowport is included
 685     from pull request 385.
 686
 687     Result: As mentioned, the wasm cross-compile will end up in
 688             targets/wasm and the nethacklib.a will end up in
 689             src.
 690
 691     The cross-compiler hints additions are enclosed inside ifdef sections
 692     and shouldn't interfere with the non-cross-compile builds using
 693     hints/linux.370 or hints/macOS.370.
 694
 695 ---
 696