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