-
Notifications
You must be signed in to change notification settings - Fork 549
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
22 changed files
with
46,520 additions
and
47 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,234 @@ | ||
| If you read this file _as_is_, just ignore the funny characters you see. It is | ||
| written in the POD format (see pod/perlpod.pod) which is specially designed to | ||
| be readable as is. | ||
|
|
||
| =head1 NAME | ||
|
|
||
| perlios - Perl under iOS, Apple TV and Apple Watch | ||
|
|
||
| =head1 SYNOPSIS | ||
|
|
||
| This document briefly describes an experimental procedure to cross compile Perl | ||
| targeting iOS, tvOS and watchOS (and their simulators) using a macOS or Mac OS | ||
| X host. | ||
|
|
||
| =head1 REQUISITES | ||
|
|
||
| In order to build your own version of Perl you will need 'make', which is part | ||
| of Apple's developer tools - also known as Xcode. From Mac OS X 10.7 "Lion" | ||
| onwards, it can be downloaded separately as the 'Command Line Tools' bundle | ||
| directly from L<https://developer.apple.com/downloads/> (you will need a free | ||
| account to log in), or as a part of the Xcode suite, freely available at the | ||
| App Store. Xcode is a pretty big app, so unless you already have it or really | ||
| want it, you are advised to get the 'Command Line Tools' bundle separately from | ||
| the link above. If you want to do it from within Xcode, go to Xcode -> | ||
| Preferences -> Downloads and select the 'Command Line Tools' option. | ||
|
|
||
| This procedure assumes that you have Xcode.app in /Applications and the SDKs in | ||
| standard locations. If they are not, the build scripts might fail. | ||
|
|
||
| Perlbrew is also necessary | ||
|
|
||
| https://perlbrew.pl/ | ||
|
|
||
| NOTE: At the moment you will need to have the same version of perl that you | ||
| want to build installed via perlbrew, as miniperl and generate_uudmap will be | ||
| copied from the corresponding version's 'build' directory. This is a temporary | ||
| solution, you might as well modify the script to use your own build | ||
|
|
||
| perlbrew install perl-5.30.3 | ||
|
|
||
| =head1 BUILD | ||
|
|
||
| The following commands will try to build perl (up to 'make test_prep' | ||
| inclusive) It is not possible tu run 'make test' on the cross compiled targes. | ||
| This will require a test app running on the device or simulator to execute the | ||
| tests and report the results. If the build succeeds it will then execute 'make | ||
| install' in ./$INSTALL_DIR choice. | ||
|
|
||
| curl -O http://www.cpan.org/src/perl-5.30.3.tar.gz tar -xzf | ||
| perl-5.30.3.tar.gz [VAR1=VALUE VAR2=VALUE] sh | ||
| perl-5.30.3/ios/build.sh/build.sh | ||
|
|
||
| =head1 QUICK INTRO | ||
|
|
||
| Following are some examples. For detailed options see next section, BUILD | ||
| OPTIONS The ios/build.sh script will create and populate directories 'bin', | ||
| 'lib' and 'share' within $INSTALL_DIR, './local' by default | ||
|
|
||
| After the build is completed several artifacts should be created similar to | ||
| this: | ||
| # bin dir | ||
| perl-5.30.3-watch-armv7k-20200619-140059.bin.tar.bz2 | ||
| # share dir | ||
| perl-5.30.3-watch-armv7k-20200619-140059.share.tar.bz2 | ||
| # lib/perl5 | ||
| perl-5.30.3-watch-armv7k-20200619-140059.lib.tar.bz2 | ||
| # complete build dir, including t | ||
| perl-5.30.3-watch-armv7k-20200619-140059.build.tar.bz2 | ||
|
|
||
| To build a release version of perl for iOS arm64 in 'local' dir: sh -x | ||
| "perl-5.30.3/ios/build.sh" | ||
|
|
||
| To build a release version of perl for iOS x86_64 simulator in './local' dir: | ||
| PERL_ARCH=x86_64 DEBUG=1 sh -x "perl-5.30.3/ios/build.sh" | ||
|
|
||
| To build a debug version of perl for iOS armv7 in './another' dir: | ||
| PERL_ARCH=armv7 DEBUG=1 INSTALL_DIR='another' sh -x "perl-5.30.3/ios/build.sh" | ||
|
|
||
| To build a release version of perl for Apple TV arm64: PERL_APPLETV=1 | ||
| MIN_VERSION=9.0 sh -x "perl-5.30.3/ios/build.sh" | ||
|
|
||
| To build a debug version perl for Apple TV: PERL_APPLETV=1 MIN_VERSION=9.0 | ||
| DEBUG=1 sh -x "perl-5.30.3/ios/build.sh" | ||
|
|
||
| To build a debug version of perl for Apple TV Simulator: PERL_APPLETV=1 | ||
| MIN_VERSION=9.0 PERL_ARCH=x86_64 DEBUG=1 sh -x "perl-5.30.3/ios/build.sh" | ||
|
|
||
| To build a debug version of perl for Apple Watch: PERL_APPLEWATCH=1 DEBUG=1 | ||
| MIN_VERSION=3.0 sh -x "perl-5.30.3/ios/build.sh" | ||
|
|
||
| To build a debug version of perl for Apple Watch Simulator: PERL_ARCH=x86_64 | ||
| PERL_APPLEWATCH=1 MIN_VERSION=3.0 DEBUG=1 sh -x "perl-5.30.3/ios/build.sh" | ||
|
|
||
| =head1 BUILD OPTIONS | ||
|
|
||
| Please note that there is no specific flag for simulator builds as all X86_64 | ||
| builds will automatically be built for the simulator. | ||
|
|
||
| The following optional environment variables can be set to customize your | ||
| build: | ||
|
|
||
| =over 2 | ||
|
|
||
| =item PERL_ARCH | ||
|
|
||
| The following architectures are supported: | ||
|
|
||
| The architecture of the perl binaries. Only one can be built at a time | ||
|
|
||
| iOS (iphone, ipad): | ||
| armv7 7.1.2 - 10.3.4 | ||
| arm64 7.1.2 - current | ||
| x86-64 8.0.0 - current simulators | ||
|
|
||
| tvOS 64 bit (Apple TV 4th and 5th generation): | ||
| arm64 11.0.0 - current | ||
| x86-64 11.0.0 - current simulators | ||
|
|
||
| watchOS: | ||
| armv7k 3.0.0 - current | ||
| x86-64: 3.0.0 - current | ||
| simulators | ||
|
|
||
| Must be one of: arm64, armv7 for iOS builds arm64 for Apple TV builds armv7k | ||
| for Apple Watch builds x86_64 for iOS simulator, Apple TV simulator or Apple | ||
| Watch builds | ||
|
|
||
| On iOS and Apple TV device builds the default is arm64 On Apple Watch | ||
| device builds the default is armv7k On all simulator builds default is | ||
| x86_64 | ||
|
|
||
| PERL_ARCH=arm64 # for iOS or tvOS | ||
|
|
||
| =item BITCODE | ||
|
|
||
| Build bitcode information into the binary. Does not apply to simulator | ||
| builds. Default for device builds is 1 BITCODE=1 | ||
|
|
||
| =item IPHONE_MIN_VERSION | ||
|
|
||
| Minimum iPhoneOS or AppleTVOS version compatible with built perl binaries. | ||
| Default for device builds is 8.0 IPHONE_MIN_VERSION=8.0 | ||
|
|
||
| =item DEBUG | ||
|
|
||
| Set to 1 if you want to produce a debug build. Debugging symbols will be put | ||
| into 'libperl.dylib.dSYM' file for source code debugging. DEBUG=1 | ||
|
|
||
| =item INSTALL_DIR | ||
|
|
||
| Set to the name of the subdirectory within your working directory (the one | ||
| you are on when you call the build.sh script) where your device or simulator | ||
| perl will be installed INSTALL_DIR='local' | ||
|
|
||
| $INSTALL_DIR allows the build to find other libraries for the target platform | ||
| and arch if you want to build XS modules by using 'lib' and 'include' | ||
| directories within | ||
|
|
||
| =item PERL_APPLETV | ||
|
|
||
| Set to 1 if you want to build for Apple TV instead of the default (iOS) | ||
| PERL_APPLETV=1 | ||
|
|
||
| =item PERL_APPLEWATCH | ||
|
|
||
| Set to 1 if you want to build for Apple Watch instead of the default (iOS) | ||
| PERL_APPLEWATCH=1 | ||
|
|
||
| =item DEVICE_SDK_PATH, SIMULATOR_SDK_PATH | ||
|
|
||
| Use these if you want to use non default SDK location with your build | ||
| SIMULATOR_SDK_PATH="/Applications/Xcode.app/Contents/Developer/Platforms/ | ||
| iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator.sdk" | ||
| DEVICE_SDK_PATH="/Applications/Xcode.app/Contents/Developer/Platforms/ | ||
| AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk" | ||
|
|
||
| =back | ||
|
|
||
| =head2 Extensions | ||
|
|
||
| It should be possible to build extensions with the build by placing the tar.gz | ||
| distributions in an ext directory besides. | ||
|
|
||
| Not all modules will work, this is being investigated | ||
|
|
||
| All extensions that have associated *.bundle objects will need to be | ||
| installed at compile time because they need to be signed to run in the device | ||
|
|
||
| It should also be possible to install pure perl modules from an app running | ||
| the embedded perl | ||
|
|
||
| =head2 Universal Binary support | ||
|
|
||
| The build script only builds one platform at a time. If you want to produce a | ||
| Universal binary, build both versions with different PERL_ARCH flags and use | ||
| the 'lipo' command to produce fat binaries from both builds that support both | ||
| arm64 and armv7. This can also be done with .dSYM debugging symbols files. | ||
|
|
||
| Simulator builds are x86_64 only. Apple TV device builds are arm64 only. Apple | ||
| Watch device builds are armv7k only. | ||
|
|
||
| x86_64 targets cannot be built with Apple bitcode support | ||
|
|
||
| =head2 Known problems | ||
|
|
||
| Nor iOS or the Apple TV provide access to a shell interpreter that the user or | ||
| the programmer can use. This has a number of implications for perl on iOS and | ||
| Apple TV | ||
|
|
||
| * exec, system calls and backticks operator are not supported. * the perl | ||
| binary that is built is of no use for Cocoa based programming, however | ||
| libperl.dylib and the built modules can be embedded on an iOS or Apple TV | ||
| application and can be consumed from C/C++/Objective-C code. * On iOS the fork | ||
| call (and others like execv) exist, however these will fail at runtime. On | ||
| Apple TV it seems to not exist at all, and the perl wrappers will always fail | ||
|
|
||
|
|
||
| =head2 Cocoa | ||
|
|
||
| You can use Cocoa from Perl on iOS, tvOS and watchOS with CamelBones, a | ||
| framework that allows access to both Foundation and UIKit classes and objects, | ||
| so that full GUI applications can be built in Perl. CamelBones can be found on | ||
| SourceForge, at L<https://github.com/jpalao/camelbones>. | ||
|
|
||
|
|
||
| =head1 AUTHOR | ||
|
|
||
| This README was written by Sherm Pendley E<lt>sherm@dot-app.orgE<gt>, and | ||
| subsequently updated by Dominic Dunlop E<lt>domo@computer.orgE<gt> and Breno G. | ||
| de Oliveira E<lt>garu@cpan.orgE<gt> and Jose Palao E<lt>jose@palao.comE<gt> | ||
|
|
||
| =head1 DATE | ||
|
|
||
| Last modified 2020-06-20. |
Oops, something went wrong.