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