<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2171/18/9/_/styles/combined.css?spaceKey=TOP&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/TOP/Building+Asterisk+SCF">Building Asterisk SCF</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~beagles">Brent Eagles</a>
</h4>
<br/>
<h4>Changes (2)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{color} <br> <br></td></tr>
<tr><td class="diff-changed-lines" >Building Asterisk SCF is pretty straightforward but does involve a few steps. First, you will need to have the proper tools installed. Besides the obvious C++ compiler, you will need a fairly recent version of a git client (current versions are at 1.7.x and should work great), and cmake 2.8 or better. Once these have been properly installed you can obtain and install the "third party" libraries required by Ice. Your system may already have versions of these libraries and header files installed, but you will want to check and make sure the versions are compatible as it can save you a lot of grief later on. Actually, you may need to install a patched version of a library in some cases so it is worthwhile downloading and checking the source distributions. After the third party libraries are installed, you obtain the Ice sources from the Asterisk SCF git server. It is essential that you use this version as it contains modifications that are currently only available <span class="diff-changed-words">there<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">, but more on that later</span>.</span> Once Ice is built, you can obtain the Asterisk SCF sources from git repository and start building. This is where CMake comes and of course the build tools for your target platform. Fortunately there are a few helper scripts that help with these last two parts. <br></td></tr>
<tr><td class="diff-unchanged" > <br>That is a lot of very general instructions. Let's address each area in a bit more detail. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{color} <br> <br></td></tr>
<tr><td class="diff-changed-lines" >As already mentioned, the core Asterisk SCF components being worked on by Digium have been implemented in C\+\+. While a certain level of compliance with recent standards is required by Ice, Asterisk SCF is written with an eye to the most recent C\+\+ standard, C\+\+11. Obviously, widespread support of C\+\+11 features just is not there but when it does, it is likely that the community as a whole will want to take advantage of the useful additions to the standard. <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Also, it is touched on a bit later on, but the</span> <span class="diff-added-words"style="background-color: #dfd;">The</span> C\+\+ library "Boost" is <span class="diff-added-words"style="background-color: #dfd;">also</span> used throughout Asterisk SCF and <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">will require</span> <span class="diff-added-words"style="background-color: #dfd;">requires</span> a certain minimal compliance with recent standards. The bottom line is, GCC 2.95.3, VS 2005, GCC 4.0.5, etc. definitely not. On Windows, it is recommended that you stick to Visual Studio 2010 at the minimum and on UNIX-like boxes GCC -4.4.x and greater is preferable. Note that Asterisk SCF may actually fail to compile with the most recent version of GCC compilers as they tend to become more strict in their compliance with the language specification. Gray areas become more black and white and, because Asterisk SCF code is built with all warnings turned on *and* with warnings treated as errors, the build will break. This is good though since we simply fix the code so that it is correct. Compilers as QA tools, who would have guessed. <span class="diff-added-words"style="background-color: #dfd;">Which brings up clang, the front end for LLVM. Unfortunately clang is not supported at this time since there are a few problems building third party libraries. Considering the advantages and increasing popularity of clang, we expect that these issues will be resolved eventually but there is no eta yet.</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>Pretty much out of the blue, we need to mention Python here. The configuration tools in Asterisk SCF are actually Python scripts and they use Ice for Python to communicate with the configuration objects implemented in the components. In order to build Ice for Python, you will need to have an Ice-supported version of Python installed, including the header files and link libraries. This means that you may need to install some additional "-dev" type packages on your Linux boxes. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Yes, this is written in a very informal, conversational voice. It was easier getting the info out this way.</td></tr></table></div>
<h3><a name="BuildingAsteriskSCF-SlideSuggestions"></a>Slide Suggestions</h3>
<p><font color="white"><br/>
<div class="panel" style="background-color: #7788FF;border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;background-color: #2022FF;"><b>Building Asterisk SCF</b></div><div class="panelContent" style="background-color: #7788FF;">
<ul>
<li>Required tools: git, cmake, C++ compiler</li>
<li>Build Ice
<ul>
<li>Obtain and build Ice dependencies (if necessary).</li>
<li>Obtain and build Ice from the Asterisk SCF Ice git repository.</li>
</ul>
</li>
<li>Obtain and build Asterisk SCF
<ul>
<li>Release and Integration repositories.</li>
<li>Git to know your git for contributing.</li>
<li>gitall-asterisk-scf.sh</li>
</ul>
</li>
</ul>
</div></div></font></p>
<p>Building Asterisk SCF is pretty straightforward but does involve a few steps. First, you will need to have the proper tools installed. Besides the obvious C++ compiler, you will need a fairly recent version of a git client (current versions are at 1.7.x and should work great), and cmake 2.8 or better. Once these have been properly installed you can obtain and install the "third party" libraries required by Ice. Your system may already have versions of these libraries and header files installed, but you will want to check and make sure the versions are compatible as it can save you a lot of grief later on. Actually, you may need to install a patched version of a library in some cases so it is worthwhile downloading and checking the source distributions. After the third party libraries are installed, you obtain the Ice sources from the Asterisk SCF git server. It is essential that you use this version as it contains modifications that are currently only available there. Once Ice is built, you can obtain the Asterisk SCF sources from git repository and start building. This is where CMake comes and of course the build tools for your target platform. Fortunately there are a few helper scripts that help with these last two parts.</p>
<p>That is a lot of very general instructions. Let's address each area in a bit more detail.</p>
<p><font color="white"><br/>
<div class="panel" style="background-color: #7788FF;border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;background-color: #2022FF;"><b>Required Tools - git</b></div><div class="panelContent" style="background-color: #7788FF;">
<ul>
<li>Free and open source.</li>
<li>Very popular and for good reason.</li>
<li>Distributed version control system.</li>
<li>Fast. Very fast.</li>
<li>Bit of a learning curve, but documentation exists to specifically help users switching from subversion etc.</li>
<li>Documentation, tutorials and books widely available, both free and for $$$. e.g. the Creative Commons Pro Git at <a href="http://progit.org/book" class="external-link" rel="nofollow">http://progit.org/book</a>.</li>
</ul>
</div></div></font></p>
<p>Git is an open source, distributed version control system that has gained great popularity over the past few years. By distributed it means that any "clone" of repository is itself a repository and itself can be cloned. It may not be immediately apparent, but this is useful for a wide variety reasons. For example, if you are working on a set changes that you want to share amongst team members or even across different machines in your development environment, you do not have to submit the changes to a central repository and update from there. You simply commit your changes in one repository and "pull" the changes from that repository into the other cloned repositories. If you need to make a fix for a particular platform, you can make the change, test it, commit it and distribute the changes to the other repositories for further testing. All of this while getting the full benefit of version controlled changes. And this is one of the benefits of git's distributed nature. </p>
<p>One of the things that quickly becomes apparent is how fast git is at cloning repositories and distributing changes. Even with large repositories containing lots of branches, the time it takes to clone a repository is very quick. While everybody wants <b>faster</b>, this responsiveness in a version control system enables agility in coding practices, especially with branching, reviewing, merging, etc.</p>
<p>Git is very cool and powerful. As in most things, this power comes at a cost of a bit of a learning curve. Although, to be fair, the learning curve is mostly <b>unlearning</b> how other version control systems work and accepting the Zen of Git. Probably the first and most important thing to learn is "DON'T PANIC". As you venture past basic git usage, you might find yourself in strange dark waters. In all but the most extreme cases, git seems to often provide you way back and it is most likely someone else has done whatever has toasted your changes and can describe how to recover. Which brings us to the topic of documentation. It seems git garners nearly as much attention as a spiffy new programming language would in the volume of books, articles and tutorials available. Some of these books are free, such as the Creative Commons Licensed book "Pro Git", available at <a href="http://progit.org" class="external-link" rel="nofollow">http://progit.org</a>. Of course, there is also the Asterisk SCF development community there to help you out of a jam should the need arise!</p>
<p><font color="white"><br/>
<div class="panel" style="background-color: #7788FF;border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;background-color: #2022FF;"><b>Required Tools - cmake</b></div><div class="panelContent" style="background-color: #7788FF;">
<ul>
<li>(bits about cmake, see Josh's stuff)</li>
</ul>
</div></div></font></p>
<p><font color="white"><br/>
<div class="panel" style="background-color: #7788FF;border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;background-color: #2022FF;"><b>Required Tools - Compilers</b></div><div class="panelContent" style="background-color: #7788FF;">
<ul>
<li>Fairly recent versions of GNU C++, Visual Studio 10 including the "Express" Version.
<ul>
<li>Asterisk SCF requires support for fairly recent C++ language standard, but not c++11.. yet <img class="emoticon" src="/wiki/images/icons/emoticons/smile.gif" height="20" width="20" align="absmiddle" alt="" border="0"/>.</li>
</ul>
</li>
<li>Python 2.6.6 is required for the configuration tools. The Python version is mostly tied to what is supported by Ice.</li>
</ul>
</div></div></font></p>
<p>As already mentioned, the core Asterisk SCF components being worked on by Digium have been implemented in C++. While a certain level of compliance with recent standards is required by Ice, Asterisk SCF is written with an eye to the most recent C++ standard, C++11. Obviously, widespread support of C++11 features just is not there but when it does, it is likely that the community as a whole will want to take advantage of the useful additions to the standard. The C++ library "Boost" is also used throughout Asterisk SCF and requires a certain minimal compliance with recent standards. The bottom line is, GCC 2.95.3, VS 2005, GCC 4.0.5, etc. definitely not. On Windows, it is recommended that you stick to Visual Studio 2010 at the minimum and on UNIX-like boxes GCC -4.4.x and greater is preferable. Note that Asterisk SCF may actually fail to compile with the most recent version of GCC compilers as they tend to become more strict in their compliance with the language specification. Gray areas become more black and white and, because Asterisk SCF code is built with all warnings turned on <b>and</b> with warnings treated as errors, the build will break. This is good though since we simply fix the code so that it is correct. Compilers as QA tools, who would have guessed. Which brings up clang, the front end for LLVM. Unfortunately clang is not supported at this time since there are a few problems building third party libraries. Considering the advantages and increasing popularity of clang, we expect that these issues will be resolved eventually but there is no eta yet.</p>
<p>Pretty much out of the blue, we need to mention Python here. The configuration tools in Asterisk SCF are actually Python scripts and they use Ice for Python to communicate with the configuration objects implemented in the components. In order to build Ice for Python, you will need to have an Ice-supported version of Python installed, including the header files and link libraries. This means that you may need to install some additional "-dev" type packages on your Linux boxes. </p>
<p><font color="white"><br/>
<div class="panel" style="background-color: #7788FF;border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;background-color: #2022FF;"><b>Building Ice - Dependencies</b></div><div class="panelContent" style="background-color: #7788FF;">
<ul>
<li>This needs to be done first.</li>
<li>"Third Party Libraries" on ZeroC website
<ul>
<li>Pre-built for some platforms, sources including required patches also available.</li>
<li>When stock packages for a particular platform will do, make sure the "dev" packages are also installed.</li>
<li>Requires a patched version of libmcpp to workaround a known bug.</li>
</ul>
</li>
</ul>
</div></div></font></p>
<p>When it comes to obtaining and installing the third party libraries required to build Ice there are a few different ways to go about it. On all platforms, you can obtain the sources for the third party libraries and build them yourself. The easiest way to go about that is to download the Ice-Third-Party archives from the ZeroC website. While there, you may notice that ZeroC provides some rpms and a Windows installer, so might decide to opt for that approach. It is worth pointing out that the Ice Slice translators work best with a patched version of libmcpp. The patch is available in the source distribution and is already applied to the binaries downloadable from the ZeroC website. If you decide to used "-dev" packages for the required libraries, you should still either install libmcpp from a ZeroC binary if there is one, or build from sources with the patch supplied in third party sources archive on their website.</p>
<p><font color="white"><br/>
<div class="panel" style="background-color: #7788FF;border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;background-color: #2022FF;"><b>Building Ice - the Ice repository</b></div><div class="panelContent" style="background-color: #7788FF;">
<ul>
<li>Includes features added for Asterisk SCF
<ul>
<li>Developed in partnership with ZeroC.</li>
<li>Incorporated in future version of Ice.</li>
</ul>
</li>
<li>New features and why the stock version of Ice will not do:
<ul>
<li>unsliceable classes</li>
<li>custom code generation for visitor class support</li>
<li>improvements to library loading for services</li>
<li>code generation fixes</li>
</ul>
</li>
</ul>
</div></div></font></p>
<p>Of course you can download the pre-built Ice binaries from the ZeroC website, but you will not get far with building Asterisk SCF. Asterisk SCF employs some concepts that were not anticipated by the ZeroC team and to a certain extent appears to be unique, the concept of propagating classes of unknown "actual" type intact or "unsliced" through intermediate services. What does this mean? Describing what we mean by "slicing" is probably a good place start. An object is sliced when it is passed as a parameter in an invocation and the <b>runtime type</b> of that object is altered to a more general or "less derived" type, either deliberately or incidentally. In Ice, you may use any object derived from a type that is allowable in the argument list of a particular method. However, if the receiving implementation has no knowledge of that actual complete runtime type, the Ice runtime will "walk" up the inheritance tree to find a type that it does know about and create an instance of that, effectively slicing off all of the extra bits. Seems reasonable, but what happens now if that object is passed through yet another method invocation and that the target implementation actually knows about that complete, original type. It is too bad, all of the additional information was "sliced" off and did not make it. This is unfortunate and not great at all when you consider the design philosophy behind Asterisk SCF. So, with Ice being open source, we endeavored to fix that. The end result was the creation of a new modifier that can be applied to Slice classes and exceptions that tells the Ice runtime to hold on to the information that would be sliced off and send it back out on the wire if that particular object instance is used in further Ice calls. The on the wire protocol is <b>not</b> affected since the Ice protocol was fortunately designed in such a way that, with a little bookkeeping, you can treat the data for the unknown type information as "relatively" opaque and simply apply some fixups to indirection and then simply write that data right back on to the "wire" when it is time to send it out again. </p>
<p>While initially conceived by Digium, it was refined in partnership with ZeroC and is expected to be incorporated into future versions of Ice.</p>
<p>In addition to unsliceable support, Digium has also added a facility for "code generation plugins" for the Slice translators. This is used for the visitor plugin which facilitates creating type specific application logic without resorting to explicit checking of type information. This is used extensively in the implementation of configuration and replication for the Asterisk SCF components.</p>
<p>There have also been some bug fixes and some improvements to IceBox service loading, etc.</p>
<p>The bottom line is if you currently use a non-Digium supplied version of Ice, you simply will not be able to build Asterisk SCF. </p>
<p><font color="white"><br/>
<div class="panel" style="background-color: #7788FF;border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;background-color: #2022FF;"><b>Building Asterisk SCF - Boost!</b></div><div class="panelContent" style="background-color: #7788FF;">
<ul>
<li>Boost is a collection of free, peer-reviewed C++ class libraries.</li>
<li>The culmination of countless years of C++ experience and hard-won best practices.</li>
<li>Wide range of platform support.</li>
<li>Answers the "the Java/C#/Python library has that" challenge.</li>
<li>boost::test is used in the tests!</li>
</ul>
</div></div></font></p>
<p>Boost is a collection of free, peer reviewed C++ class libraries and is the result of the C++ development community coming together and gathering their hard-won knowledge of what does and does not work in C++. In some cases, boost contains implementations of classes and features that have ultimately found their way into the C++ standard! In short, if you are coding in C++ and are <b>not</b> using boost, you probably should have a good reason. No, Ice does not use boost but there are several good reasons for that are outside of the current scope. Some of the most frequently used boost classes are in the areas of threading, locking, and shared pointers. In addition, boost::test is <b>the</b> chosen framework for building tests in C++.</p>
<p>There are several ways to obtain boost. As always you can download the source and build it yourself. On some platforms (Windows!) this can be a little tricky to get right and you may be better off using a pre-existing binary distribution with an installer, like (insert a link to the best distro here). On linux, you may be able to simply download and install boost from your package manager. Make sure it is recent version and that you get the "-dev" packages!</p>
<p><font color="white"><br/>
<div class="panel" style="background-color: #7788FF;border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;background-color: #2022FF;"><b>Building Asterisk SCF - the Repositories</b></div><div class="panelContent" style="background-color: #7788FF;">
<ul>
<li>Integration and Release repositories</li>
<li>asterisk-scf/integration/sip and asterisk-scf/release/sip</li>
<li>Repository-per-component</li>
<li>asterisk-scf/release/sip, asterisk-scf/release/bridging, etc.</li>
<li>Slice collections</li>
<li>asterisk-scf/slice</li>
<li>Non-component foundation repositories (slice, ice-util-cpp)</li>
<li>How cmake ties it all together.</li>
</ul>
</div></div></font></p>
<p>For each component or library, there are two different versions of repository: release and integration. The release repositories contain the master branch (synonymous with svn's "trunk") for a particular component as well as any "release" branches. The integration repositories is where all of the <b>in development</b> branches live. This is one of those scenarios made possible by git. Once a development branch has been tested, reviewed and deemed fit to be included in master, it is merged with your local copy of the master branch – this is where you resolve conflicts and do that last minute "does it build and work" test – and then simply push it to the release repository. That's pretty much it. </p>
<p>As already mentioned, the sources are organized on a repository-per-component basis. There is a small exception to this as a component's replication service is included in the same repository, but due to the fairly tight coupling between a component's implementation and its corresponding replication service, separating them would serve no practical purpose. </p>
<p>Not all repositories are for components. Code and resources shared by all components or that support the development process in general are organized into repositories according to purpose and dependencies. For example, all of the Slice files that collectively define the Asterisk SCF API are in the "slice" repository. The Asterisk SCF cmake support code is in its own repository as are utility classes that use Ice (ice-util-cpp) and utility classes that don't (util-cpp).</p>
<p>Major third party libraries that are essential to Asterisk SCF have also been imported into repositories, e.g. the aforementioned ZeroC Ice and Teluu's pjproject.</p>
<p>It is a good time to point out that there is a special repository containing scripts and support for building all of the Asterisk SCF components, asterisk-scf/integration/gitall. This repository pulls in a copy of the require cmake support files and the gitall-astersisk-scf.sh script. Running this script will automatically clone all of the Asterisk SCF release repositories. This vastly simplifies the process of getting the Asterisk SCF sources and getting started. After that has successfully run, all that remains is to create a build directory, run cmake and start the build. If you jumped the gun and started downloading all of the repositories before you got to this paragraph, aren't you sorry you didn't read the whole thing?</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=TOP">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/TOP/Building+Asterisk+SCF">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=19006201&revisedVersion=12&originalVersion=11">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/Building+Asterisk+SCF?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>