OLD | NEW |
(Empty) | |
| 1 # Build scripts that publish pre-compiled protoc artifacts |
| 2 ``protoc`` is the compiler for ``.proto`` files. It generates language bindings |
| 3 for the messages and/or RPC services from ``.proto`` files. |
| 4 |
| 5 Because ``protoc`` is a native executable, the scripts under this directory |
| 6 build and publish a ``protoc`` executable (a.k.a. artifact) to Maven |
| 7 repositories. The artifact can be used by build automation tools so that users |
| 8 would not need to compile and install ``protoc`` for their systems. |
| 9 |
| 10 ## Versioning |
| 11 The version of the ``protoc`` artifact must be the same as the version of the |
| 12 Protobuf project. |
| 13 |
| 14 ## Artifact name |
| 15 The name of a published ``protoc`` artifact is in the following format: |
| 16 ``protoc-<version>-<os>-<arch>.exe``, e.g., ``protoc-3.0.0-alpha-3-windows-x86_6
4.exe``. |
| 17 |
| 18 ## System requirement |
| 19 Install [Apache Maven](http://maven.apache.org/) if you don't have it. |
| 20 |
| 21 The scripts only work under Unix-like environments, e.g., Linux, MacOSX, and |
| 22 Cygwin or MinGW for Windows. Please see ``README.md`` of the Protobuf project |
| 23 for how to set up the build environment. |
| 24 |
| 25 ## To install artifacts locally |
| 26 The following command will install the ``protoc`` artifact to your local Maven r
epository. |
| 27 ``` |
| 28 $ mvn install |
| 29 ``` |
| 30 |
| 31 ## Cross-compilation |
| 32 The Maven script will try to detect the OS and the architecture from Java |
| 33 system properties. It's possible to build a protoc binary for an architecture |
| 34 that is different from what Java has detected, as long as you have the proper |
| 35 compilers installed. |
| 36 |
| 37 You can override the Maven properties ``os.detected.name`` and |
| 38 ``os.detected.arch`` to force the script to generate binaries for a specific OS |
| 39 and/or architecture. Valid values are defined as the return values of |
| 40 ``normalizeOs()`` and ``normalizeArch()`` of ``Detector`` from |
| 41 [os-maven-plugin](https://github.com/trustin/os-maven-plugin/blob/master/src/mai
n/java/kr/motd/maven/os/Detector.java). |
| 42 Frequently used values are: |
| 43 - ``os.detected.name``: ``linux``, ``osx``, ``windows``. |
| 44 - ``os.detected.arch``: ``x86_32``, ``x86_64`` |
| 45 |
| 46 For example, MingGW32 only ships with 32-bit compilers, but you can still build |
| 47 32-bit protoc under 64-bit Windows, with the following command: |
| 48 ``` |
| 49 $ mvn install -Dos.detected.arch=x86_32 |
| 50 ``` |
| 51 |
| 52 ## To push artifacts to Maven Central |
| 53 Before you can upload artifacts to Maven Central repository, make sure you have |
| 54 read [this page](http://central.sonatype.org/pages/apache-maven.html) on how to |
| 55 configure GPG and Sonatype account. |
| 56 |
| 57 You need to perform the deployment for every platform that you want to |
| 58 suppport. DO NOT close the staging repository until you have done the |
| 59 deployment for all platforms. Currently the following platforms are supported: |
| 60 - Linux (x86_32 and x86_64) |
| 61 - Windows (x86_32 and x86_64) with |
| 62 - Cygwin with MinGW compilers (both x86_32 and x86_64) |
| 63 - MSYS with MinGW32 (x86_32 only) |
| 64 - MacOSX (x86_32 and x86_64) |
| 65 |
| 66 Use the following command to deploy artifacts for the host platform to a |
| 67 staging repository. |
| 68 ``` |
| 69 $ mvn clean deploy -P release |
| 70 ``` |
| 71 It creates a new staging repository. Go to |
| 72 https://oss.sonatype.org/#stagingRepositories and find the repository, usually |
| 73 in the name like ``comgoogle-123``. |
| 74 |
| 75 You will want to run this command on a different platform. Remember, in |
| 76 subsequent deployments you will need to provide the repository name that you |
| 77 have found in the first deployment so that all artifacts go to the same |
| 78 repository: |
| 79 ``` |
| 80 $ mvn clean deploy -P release -Dstaging.repository=comgoogle-123 |
| 81 ``` |
| 82 |
| 83 A 32-bit artifact can be deployed from a 64-bit host with |
| 84 ``-Dos.detected.arch=x86_32`` |
| 85 |
| 86 When you have done deployment for all platforms, go to |
| 87 https://oss.sonatype.org/#stagingRepositories, verify that the staging |
| 88 repository has all the binaries, close and release this repository. |
| 89 |
| 90 ### Tips for deploying on Linux |
| 91 We build on Centos 6.6 to provide a good compatibility for not very new |
| 92 systems. We have provided a ``Dockerfile`` under this directory to build the |
| 93 environment. It has been tested with Docker 1.6.1. |
| 94 |
| 95 To build a image: |
| 96 ``` |
| 97 $ docker build -t protoc-artifacts . |
| 98 ``` |
| 99 |
| 100 To run the image: |
| 101 ``` |
| 102 $ docker run -it --rm=true protoc-artifacts |
| 103 ``` |
| 104 |
| 105 The Protobuf repository has been cloned into ``/protobuf``. |
| 106 |
| 107 ### Tips for deploying on Windows |
| 108 Under Windows the following error may occur: ``gpg: cannot open tty `no tty': |
| 109 No such file or directory``. This can be fixed by configuring gpg through an |
| 110 active profile in ``.m2\settings.xml`` where also the Sonatype password is |
| 111 stored: |
| 112 ```xml |
| 113 <settings> |
| 114 <servers> |
| 115 <server> |
| 116 <id>ossrh</id> |
| 117 <username>[username]</username> |
| 118 <password>[password]</password> |
| 119 </server> |
| 120 </servers> |
| 121 <profiles> |
| 122 <profile> |
| 123 <id>gpg</id> |
| 124 <properties> |
| 125 <gpg.executable>gpg</gpg.executable> |
| 126 <gpg.passphrase>[password]</gpg.passphrase> |
| 127 </properties> |
| 128 </profile> |
| 129 </profiles> |
| 130 <activeProfiles> |
| 131 <activeProfile>gpg</activeProfile> |
| 132 </activeProfiles> |
| 133 </settings> |
| 134 ``` |
| 135 |
| 136 ### Tested build environments |
| 137 We have succesfully built artifacts on the following environments: |
| 138 - Linux x86_32 and x86_64: |
| 139 - Centos 6.6 (within Docker 1.6.1) |
| 140 - Ubuntu 14.04.2 64-bit |
| 141 - Windows x86_32: MSYS with ``mingw32-gcc-g++ 4.8.1-4`` on Windows 7 64-bit |
| 142 - Windows x86_64: Cygwin64 with ``mingw64-x86_64-gcc-g++ 4.8.3-1`` on Windows 7
64-bit |
| 143 - Mac OS X x86_32 and x86_64: Mac OS X 10.9.5 |
OLD | NEW |