Home | History | Annotate | only in /external/protobuf/protoc-artifacts
Up to higher level directory
NameDateSize
build-protoc.sh06-Dec-20176.5K
Dockerfile06-Dec-20171.6K
pom.xml06-Dec-20174.4K
README.md06-Dec-20175.2K

README.md

      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_64.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 repository.
     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/main/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 support. 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 successfully 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
    144