Reviewed-by: Andrew Fish <af...@apple.com> > On Jul 21, 2021, at 4:56 PM, Rebecca Cran <rebe...@bsdio.com> wrote: > > The existing instructions no longer work on macOS Big Sur and Xcode 12.5. > Update them to include for example using lldb instead of gdb, installing > XQuartz, and using modern names such as macOS instead of Mac OS X. > > Also, since MacPorts is less popular these days, remove instructions for > installing tools with it, leaving steps for using Homebrew. > > Signed-off-by: Rebecca Cran <rebe...@bsdio.com> > --- > Xcode.md | 172 +++++++++----------- > 1 file changed, 78 insertions(+), 94 deletions(-) > > diff --git a/Xcode.md b/Xcode.md > index 3d220a5..8af2653 100644 > --- a/Xcode.md > +++ b/Xcode.md > @@ -1,43 +1,28 @@ > -This page provides step-by-step instructions for setting up a > [http://www.tianocore.org/edk2/ EDK II] build environment on Mac OS X systems > using the Xcode development tools. These steps have been verified with macOS > Sierra Version 10.12.4 > +This page provides step-by-step instructions for setting up a [EDK > II](https://github.com/tianocore/tianocore.github.io/wiki/EDK-II) build > environment on macOS systems using the Xcode development tools. These steps > have been verified with macOS Big Sur 11.3.1 > > -# Mac OS X Xcode > -Download the latest version of [Xcode](https://developer.apple.com/xcode) > (9.4.1 as of this writing) from the Mac App Store. After installing Xcode, > you will additionally need to install the extra command-line tools. To do > this, at a Terminal prompt, enter: > +# macOS Xcode > +Download the latest version of [Xcode](https://developer.apple.com/xcode) > (12.5 as of 2021-05-09) from the Mac App Store. After installing Xcode, you > will additionally need to install the extra command-line tools. To do this, > at a Terminal prompt, enter: > ``` > $ xcode-select --install > ``` > ## Additional Development Tools > -While Xcode provides a full development environment as well as a suite of > different utilities, it does not provide all tools required for Tianocore > development. These tools can be provided in a number of ways, but the two > most popular ways come from [Brew](https://brew.sh) and > [MacPorts](https://www.macports.org/install.php). Installation information > is provided at the previous links. > - > -### MacPorts Tips > -* If you work behind a firewall and need to pass your network traffic > through a proxy, ensure you set the environment variable RSYNC_PROXY to your > http proxy in the form of `proxy.dns.name:port_number`. > - * Remember that `sudo` by default drops most environment variables. Add > the `-E` option to tell `sudo` to keep your environment variables. > -* When installing MacPorts packages, if you would like to build from source > like traditional [FreeBSD Ports](https://en.wikipedia.org/wiki/FreeBSD_Ports) > systems, add the `-s` option to the command line. Otherwise, default > behavior is to pull precompiled packages. > +While Xcode provides a full development environment as well as a suite of > different utilities, it does not provide all tools required for TianoCore > development. These tools can be provided in a number of ways, but the most > popular way comes from [Brew](https://brew.sh). Installation information is > provided at the previous link. > > ## Install mtoc > The mtoc utility is required to convert from the macOS Mach-O image format to > the PE/COFF format as required by the UEFI specification. > > ### Brew Instructions > ``` > -$ brew install mtoc > -``` > -## MacPorts Instructions > -``` > -$ sudo port install cctools > +$ brew install mtoc > ``` > -By default, this will install `mtoc` at `/opt/local/bin/mtoc`. > # Install NASM > > -The assembler used for EDK II builds is Netwide Assembler (NASM). The latest > version of NASM is available from http://www.nasm.us/. > +The assembler used for EDK II builds is Netwide Assembler (NASM). The latest > version of NASM is available from https://nasm.us/. > ## Brew Instructions > ``` > $ brew install nasm > $ brew upgrade nasm > ``` > -## MacPorts Instructions > -``` > -$ sudo port install nasm > -``` > -By default this installs `nasm` at `/opt/local/bin/nasm`. > > # Install ACPI Compiler > > @@ -47,26 +32,20 @@ In order to support EDK II firmware builds, the latest > version of the ASL compil > $ brew install acpica > $ brew upgrade acpica > ``` > -## MacPorts Install > -``` > -$ sudo port install acpica > -``` > -By default this installs `iasl` at `/opt/local/bin/iasl` > + > +# Install XQuartz > + > +The EmulatorPkg requires headers from X11, which are provided by the XQuartz > project. Install it from https://www.xquartz.org/. > > # Install QEMU Emulator > > -On order to support running the OVMF platforms from the OvmfPkg, the QEMU > emulator from http://www.qemu.org/ must be installed. > +On order to support running the OVMF platforms from the OvmfPkg, the QEMU > emulator from https://www.qemu.org/ must be installed. > > ## Brew Install > ``` > $ brew install qemu > $ brew upgrade qemu > ``` > -## MacPorts Install > -``` > -$ sudo port install qemu > -``` > -By default qemu is installed in `/opt/local/bin`. > ## Update PATH environment variable > > Tools installed using the `brew` command are placed in `/usr/local/bin`. The > `PATH` environment variable must be updated so the newly installed tools are > used instead of older pre-installed tools. > @@ -75,11 +54,6 @@ Tools installed using the `brew` command are placed in > `/usr/local/bin`. The `P > export PATH=/usr/local/bin:$PATH > ``` > > -Tools installed using the `port` should automatically be in your shell's > PATH. If not, you can manually set it by: > -``` > -export PATH=/opt/local/bin:$PATH > -``` > - > # Verify tool versions > > Run the following commands to verify the versions of the tools that have been > installed. > @@ -97,84 +71,94 @@ Pick the location you want to down load the files to and > `cd` to that directory: > ``` > cd ~/work > git clone https://github.com/tianocore/edk2.git > +cd edk2 > +git submodule update --init > ``` > > -# Build from Command Line/Debug with gdb > +# Build from Command Line/Debug with lldb > > -Build the UnixPkg: > +Build the EmulatorPkg: > > ``` > -cd ~/work/edk2/UnixPkg > +cd ~/work/edk2/EmulatorPkg > ./build.sh > ``` > > -Debug the UnixPkg > +Debug the EmulatorPkg > > ``` > ./build.sh run > > -Building from: /Users/fish/work/edk2 > +Initializing workspace > +/Users/bcran/src/edk2/BaseTools > +Loading previous configuration from /Users/bcran/src/edk2/Conf/BuildEnv.sh > +Using EDK2 in-source Basetools > +WORKSPACE: /Users/bcran/src/edk2 > +EDK_TOOLS_PATH: /Users/bcran/src/edk2/BaseTools > +CONF_PATH: /Users/bcran/src/edk2/Conf > using prebuilt tools > -Reading symbols for shared libraries ...... done > -Breakpoint 1 at 0xce84: file /Users/fish/work/edk2/UnixPkg/Sec/SecMain.c, > line 1070. > -(gdb) > -``` > - > -Type `r` at the gdb prompt (don't forget to hit carriage return) to boot the > emulator. Ctrl-c in the terminal window will break in to gdb. bt is the stack > backtrace command: > - > -``` > -^C > -Program received signal SIGINT, Interrupt. > -0x92423806 in __semwait_signal () > -(gdb) bt > -#0 0x92423806 in __semwait_signal () > -#1 0x9244f441 in nanosleep$UNIX2003 () > -#2 0x0000b989 in msSleep (Milliseconds=0x14) at > /Users/fish/work/Migration/edk2/UnixPkg/Sec/UnixThunk.c:102 > -#3 0x0000acf5 in UgaCheckKey (UgaIo=0x2078d0) at > /Users/fish/work/Migration/edk2/UnixPkg/Sec/UgaX11.c:380 > -#4 0x0000d8b7 in _GasketUintn () at > /Users/fish/work/Migration/edk2/Build/Unix/DEBUG_XCODE32/IA32/UnixPkg/Sec/SecMain/OUTPUT/Ia32/Gasket.iii:63 > -#5 0x0000d801 in GasketUgaCheckKey (UgaIo=0x2078d0) at > /Users/fish/work/Migration/edk2/UnixPkg/Sec/Gasket.c:406 > -#6 0x454a25fb in UnixUgaSimpleTextInWaitForKey (Event=0x45603610, > Context=0x45382110) at > /Users/fish/work/Migration/edk2/UnixPkg/UnixUgaDxe/UnixUgaInput.c:169 > -#7 0x45faad3a in CoreDispatchEventNotifies (Priority=0x10) at > /Users/fish/work/Migration/edk2/MdeModulePkg/Core/Dxe/Event/Event.c:185 > -#8 0x45faa639 in CoreRestoreTpl (NewTpl=0x4) at > /Users/fish/work/Migration/edk2/MdeModulePkg/Core/Dxe/Event/Tpl.c:114 > -#9 0x45f9f197 in CoreReleaseLock (Lock=0x45fb1024) at > /Users/fish/work/Migration/edk2/MdeModulePkg/Core/Dxe/Library/Library.c:102 > -#10 0x45faabd6 in CoreReleaseEventLock () at > /Users/fish/work/Migration/edk2/MdeModulePkg/Core/Dxe/Event/Event.c:113 > -#11 0x45fab26c in CoreCheckEvent (UserEvent=0x45603210) at > /Users/fish/work/Migration/edk2/MdeModulePkg/Core/Dxe/Event/Event.c:562 > -#12 0x45fab2db in CoreWaitForEvent (NumberOfEvents=0x1, > UserEvents=0x45f94cc4, UserIndex=0x45f94cb8) at > /Users/fish/work/Migration/edk2/MdeModulePkg/Core/Dxe/Event/Event.c:621 > -#13 0x49ce9557 in ?? () > -#14 0x49cf0344 in ?? () > -#15 0x49ce3bc2 in ?? () > -#16 0x49ce3ae1 in ?? () > -#17 0x45f9e4e3 in CoreStartImage (ImageHandle=0x49e31e10, > ExitDataSize=0x45f94eec, ExitData=0x45f94ee8) at > /Users/fish/work/Migration/edk2/MdeModulePkg/Core/Dxe/Image/Image.c:1260 > -#18 0x4550cccc in BdsLibBootViaBootOption (Option=0x49ffa110, > DevicePath=0x49ffa190, ExitDataSize=0x45f94eec, ExitData=0x45f94ee8) at > /Users/fish/work/Migration/edk2/IntelFrameworkModulePkg/Library/GenericBdsLib/BdsBoot.c:382 > -#19 0x455252a9 in BdsBootDeviceSelect () at > /Users/fish/work/Migration/edk2/IntelFrameworkModulePkg/Universal/BdsDxe/BdsEntry.c:214 > -#20 0x455255bc in BdsEntry (This=0x4552d01c) at > /Users/fish/work/Migration/edk2/IntelFrameworkModulePkg/Universal/BdsDxe/BdsEntry.c:356 > -#21 0x45fad7e8 in DxeMain (HobStart=0x45f70010) at > /Users/fish/work/Migration/edk2/MdeModulePkg/Core/Dxe/DxeMain/DxeMain.c:425 > -#22 0x45fadd1d in ProcessModuleEntryPointList (HobStart=0x42020000) at > /Users/fish/work/Migration/edk2/Build/Unix/DEBUG_XCODE32/IA32/MdeModulePkg/Core/Dxe/DxeMain/DEBUG/AutoGen.c:287 > -#23 0x45f97773 in _ModuleEntryPoint (HobStart=0x42020000) at > /Users/fish/work/Migration/edk2/MdePkg/Library/DxeCoreEntryPoint/DxeCoreEntryPoint.c:54 > -(gdb) > +(lldb) target create "./Host" > +Current executable set to > '/Users/bcran/src/edk2/Build/EmulatorX64/DEBUG_XCODE5/X64/Host' (x86_64). > +(lldb) command script import > /Users/bcran/src/edk2/EmulatorPkg/Unix/lldbefi.py > +Type r to run emulator. SecLldbScriptBreak armed. EFI modules should now get > source level debugging in the emulator. > +(lldb) script lldb.debugger.SetAsync(True) > +(lldb) run > +Process 12155 launched: > '/Users/bcran/src/edk2/Build/EmulatorX64/DEBUG_XCODE5/X64/Host' (x86_64) > + > +EDK II UNIX Host Emulation Environment from http://www.tianocore.org/edk2/ > + BootMode 0x00 > + OS Emulator passing in 128 KB of temp RAM at 0x102000000 to SEC > + FD loaded from ../FV/FV_RECOVERY.fd at 0x102020000 contains SEC Core > +... > +``` > + > +Type `process interrupt` at the lldb prompt (don't forget to hit carriage > return) to pause execution. Ctrl-c in the terminal window will quit lldb. > `bt` is the stack backtrace command: > + > +``` > +Process 12420 stopped > +* thread #1, queue = 'com.apple.main-thread', stop reason = signal SIGSTOP > + frame #0: 0x00007fff2033cc22 libsystem_kernel.dylib:__semwait_signal() + > 10 > +libsystem_kernel.dylib`__semwait_signal: > +-> 0x7fff2033cc22 <+10>: jae 0x7fff2033cc2c ; <+20> > + 0x7fff2033cc24 <+12>: movq %rax, %rdi > + 0x7fff2033cc27 <+15>: jmp 0x7fff2033b72d ; cerror > + 0x7fff2033cc2c <+20>: retq > +Target 0: (Host) stopped. > +(lldb) bt > +* thread #1, queue = 'com.apple.main-thread', stop reason = signal SIGSTOP > + * frame #0: 0x00007fff2033cc22 libsystem_kernel.dylib:__semwait_signal() + > 10 > + frame #1: 0x00007fff202bcc2a libsystem_c.dylib:nanosleep() + 196 > + frame #2: 0x0000000100005e55 Host:SecCpuSleep() + 37 at > /Users/bcran/src/edk2/EmulatorPkg/Unix/Host/EmuThunk.c:334 > + frame #3: 0x000000010000e96e Host:GasketSecCpuSleep() + 11 at > /Users/bcran/src/edk2/Build/EmulatorX64/DEBUG_XCODE5/X64/EmulatorPkg/Unix/Host/Host/OUTPUT/X64/Gasket.iiii:283 > + frame #4: 0x0000000106f985e9 DxeCore.dll:CoreDispatchEventNotifies() + > 264 at /Users/bcran/src/edk2/MdeModulePkg/Core/Dxe/Event/Event.c:194 > + frame #5: 0x0000000106f97fce DxeCore.dll:CoreRestoreTpl() + 227 at > /Users/bcran/src/edk2/MdeModulePkg/Core/Dxe/Event/Tpl.c:131 > + frame #6: 0x0000000106f989db DxeCore.dll:CoreSignalEvent() + 111 at > /Users/bcran/src/edk2/MdeModulePkg/Core/Dxe/Event/Event.c:566 > + frame #7: 0x0000000106f98b01 DxeCore.dll:CoreWaitForEvent() + 94 at > /Users/bcran/src/edk2/MdeModulePkg/Core/Dxe/Event/Event.c:707 > + frame #8: 0x0000000113e8e54c BdsDxe.dll:BdsWaitForSingleEvent() + 127 at > /Users/bcran/src/edk2/MdeModulePkg/Universal/BdsDxe/BdsEntry.c:250 > + frame #9: 0x0000000113e8e70b BdsDxe.dll:BdsWait() + 215 at > /Users/bcran/src/edk2/MdeModulePkg/Universal/BdsDxe/BdsEntry.c:328 > + frame #10: 0x0000000113e8dffb BdsDxe.dll:BdsEntry() + 2612 at > /Users/bcran/src/edk2/MdeModulePkg/Universal/BdsDxe/BdsEntry.c:1012 > + frame #11: 0x0000000106f9bbd6 DxeCore.dll:DxeMain() + 2791 at > /Users/bcran/src/edk2/MdeModulePkg/Core/Dxe/DxeMain/DxeMain.c:551 > + frame #12: 0x0000000106f9ed8f DxeCore.dll:_ModuleEntryPoint() + 20 at > /Users/bcran/src/edk2/MdePkg/Library/DxeCoreEntryPoint/DxeCoreEntryPoint.c:48 > + frame #13: 0x0000000106fdd02f DxeIpl.dll:InternalSwitchStack() + 15 > + frame #14: 0x0000000106fdc0b6 DxeIpl.dll:HandOffToDxeCore() + 546 at > /Users/bcran/src/edk2/MdeModulePkg/Core/DxeIplPeim/X64/DxeLoadFunc.c:126 > + frame #15: 0x0000000106fda78a DxeIpl.dll:DxeLoadCore() + 1354 at > /Users/bcran/src/edk2/MdeModulePkg/Core/DxeIplPeim/DxeLoad.c:449 > + frame #16: 0x0000000106ff1d7c > + frame #17: 0x00000001020255c6 PeiCore.dll:PeiCore() + 1982 at > /Users/bcran/src/edk2/MdeModulePkg/Core/Pei/PeiMain/PeiMain.c:331 > + frame #18: 0x000000010202a82c PeiCore.dll:PeiCheckAndSwitchStack() + > 1171 at > /Users/bcran/src/edk2/MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c:842 > + frame #19: 0x000000010202b853 PeiCore.dll:PeiDispatcher() + 1206 at > /Users/bcran/src/edk2/MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c:1609 > +(lldb) > + > ``` > > # Build and Debug from Xcode > -To build from the Xcode GUI open > ~/work/edk2/UnixPkg/Xcode/xcode_project/xcode_project.xcodeproj. You can > build, clean, and source level debug from the Xcode GUI. You can hit the > Build and Debug button to start the build process. You need to need to hit > command-shift-B to show the output of the build. Click Pause to break into > the debugger. > - > -[[File:Xcode.jpg]] > +To build from the Xcode GUI open > ~/work/edk2/EmulatorPkg/Unix/Xcode/xcode_project64/xcode_project.xcodeproj. > You can build, clean, and source level debug from the Xcode GUI. You can hit > the Build and Debug button to start the build process. You need to need to > hit command-shift-B to show the output of the build. Click Pause to break > into the debugger. > > The stack trace contains items that show as ?? since the default shell is > checked in as a binary. `nanosleep$UNIX2003` and `__semwait_signal` are POSIX > library calls and you do not get C source debug with these symbols. > > -# Source Level Debug Shell > - > -It is possible to get source level debug for the EFI Shell by pulling these > projects from source control and building them. > - > -Instructions for building and hooking in the shell are located in the > [https://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Gcc-shell > gcc-shell] project. > - > -Please note the gcc-shell and UnixPkg build separately, so if you update > shell code you need to build the shell to see the changes. The following > screen shot shows being able to source level debug the shell: > - > -[[File:Xcode_good.jpg]] > +*Note* The Xcode project is currently (as of 2021-05-09) broken. > > # See Also > > -* [[Step-by-step instructions]] > - > # Continue with common instructions > > -The [remaining instructions](../Common-instructions) are common for most > UNIX-like systems. > +The [remaining > instructions](https://github.com/tianocore/tianocore.github.io/wiki/Common-instructions-for-Unix) > are common for most UNIX-like systems. > -- > 2.30.1 (Apple Git-130) > > > > > > >
-=-=-=-=-=-=-=-=-=-=-=- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#78044): https://edk2.groups.io/g/devel/message/78044 Mute This Topic: https://groups.io/mt/84369241/21656 Group Owner: devel+ow...@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com] -=-=-=-=-=-=-=-=-=-=-=-
