Group: LibreDWG

From LibrePlanet
Revision as of 13:09, 25 August 2011 by Pbaeza (talk | contribs) (Who uses it?: Application addition that uses this library)
Jump to: navigation, search

Welcome the GNU LibreDWG hackers' wiki. For general information about the project, please check the official website.

This wiki is mainly intended to help developers or advanced users checkout the latest source code, compile, test, modify and submit changes to LibreDWG. Feel free to contribute to this page. If you are creating a new page, please put it under the LibreDWG tree, eg. http://groups.fsf.org/wiki/LibreDWG/TestSuite.

LibreDWG's source code and administrative tools (mailing lists, bug, patch and support trackers) are hosted at Savannah. We ask contributors to create a new user account and log in prior to submitting tracker items (one could submit bugs anonymously, though). You don't need to join the LibreDWG Savannah group in order to submit bug reports or patches. Please don't do this unless you are instructed to.

There are no official binary nor source releases yet. Therefore, anyone who wants to use or test LibreDWG will have to checkout from the git repository and build from source.

Checking out

The source code is hosted in a git repository. Check out git's website if you don't know what git is (hint: sudo apt-get install git-core git). To check out as an anonymous user:

git clone git://git.sv.gnu.org/libredwg.git


Dependencies

You need basic development tools (gcc, autoconf and libtool to compile libredwg. In debian-like distributions, install the build-essential, autoconf and libtool packages).

Other packages needed:

  • SWIG] 1.7 or later
  • TeXinfo
  • Python development headers (debian: python-dev yum: python-devel)

Building

cd to the libredwg folder created by git, and run the following commands in a terminal:

sh autogen.sh
./configure --enable-trace (this will enable debugging messages)
make
sudo make install
make check

These commands will, respectively, build and configure the building environment, compile the library's source code, install it to /usr/local and compile the tests/examples. If you get any errors, please contact us through the mailing list.

If you want to build under an OS made in Redmond, check LibreDWG/BuildingWithCygwin. From user reports, we know that LibreDWG builds and run correctly in the following CPU architectures: x86, x86_64 (intel) and ppc (older macbooks). If you are able to build and run it in successfully (or not) in other architectures, let us know.

Testing

LibreDWG comes with several examples (under the examples folder) that can be used for testing purposes. The most advanced example is testSVG.

export LIBREDWG_TRACE=3
cd examples
./testSVG yourdwgfile.dwg > yourconverteddwgfile.svg

If you get any errors (specially segfaults) and want to submit a bug, please attach a file with your output. To redirect all output, including stderr to a file:

./testSVG yourdwgfile.dwg 2&> test.out

If possible, add a link to the tested DWG file to the submission. We can't do much if we can't access the file. Don't attach DWG files to the submission, specially if you don't have copy rights over them.

We are building a test suite.

Hacking and submitting patches

You are welcome to get your hands dirty and put down some code. Although, you should be aware of some details:

  • Please follow the GNU Coding Standards, specially the GNU identation style.
  • Be aware that the copyright over your work will need to be assinged to the Free Software Foundation. If it is a small contribution, you won't need to sign any papers. We have decided this because the FSF will enforce the GPL for the program if someone violates it, and will act juridically if necessary. Although, you still get the credit for your work.
  • You'll probably need to understand the internals of the DWG format. The Open Design Alliance provides a reverse-engineered DWG specification.

Please be sure to work on the latest revision. Run git pull from time to time and before generating patches.

After your changes are done and well tested, generate a patch with format-patch:

checkout a working copy as described above. cd to the directory where the source code is, and then

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com 

(compile, edit, test)
git add <files that you changed>
git commit
(please format your commit message as described in the HACKING file)

(compile, edit, test)
git commit...

git format-patch origin

The git format-patch command will generate one patch for each commit (don't hesitate making various commits if you are working on different subjects/tasks).

Don't send patches to the mailing list! Submit each patch separately to the patch tracker.

If you are not very familiar with git, check the git documentation. You have to run "git config" only once. This will configure git to make your name and email appear on your commits.

For further information, please read the HACKING file in the root of the source tree.

If you don't know how/where to start working, please read the following items:

Roadmap

This is a rough development roadmap:

  • v0.4 - entity and object parsing (read-only)
  • v0.5 through v1.0 - API and bindings, that is, bindings to languages such as Python and C++, plus a reasonable API, which won't exclude the direct struct access if the user wishes.
  • v2.0 - encode support

We are actually working on all of them, but the earlier milestones seem more feasible. It is not clear when we'll make the first beta release (0.4).

DWG versions

Currently we support only R13, R14 and R2000 DWG versions. We won't support earlier versions. R2004 and R2007 are on the way. We won't support R2010 unless we find documentation about it.

We've already written entity/object decoding/encoding for all versions from R13 to R2007, but R2007 header and file structure parsing are missing or incomplete. R2010 documentation is almost non-existent.

  • R2007: we are stuck with a Reed-Solomon encrypted header. If you know something on this subject, please contact us.
  • R2010: we need more information about the file structure to start coding something

Bindings and extensions

Python bindings have been generated with SWIG. Although, the python module is still buggy.

The GNU project guidelines encourage developers to use guile as an extension framework. Guile uses LISP as an extension language. DWG is an extensible format: people can write custom entities, and we should provide some plugin feature that allows people to write custom code do interpret them.

Error codes

Any C library should, ideally, have no stdout/stderr output and communicate errors to the application through error codes. We need to improve that.

Testing Suite

We need an automated test suite to make it easy to verify and ensure that code changes won't break the DWG parser. It would also allow users to test the library with their own files in an easy way. The first step is gathering a collection of DWG files "Saved as..." to various DWG versions. These files must be released to the public domain.

Guruprasad Rane has written an initial test suite. It will be committed to the git repository soon.

Questions

  1. Where are we going to upload large files to : archive.org?
  2. How are we going to convert them in many formats, we need someone with a autocad converter software.
  3. We should be recycling test cases from other cad software, from svg and inkscape.
  4. We should be publishing profiles of code coverage for each test.
  5. We should be marking up some document that contains the elements that we have seen so far.

AutoCAD

If you can't program, but have some understanding of AutoCAD, you could help us. Several developers haven't ever used AutoCAD or any other mainstream CAD program, and we usually have difficulties understanding the semantics of DWG (how does an aligned dimension look like?), despite being almost experts regarding the low level file syntax.

HANDLES

If you have any knowledge about how handles work internally, please contact us. We could use some help!

Google Summer of Code

The GNU project has been accepted as a mentoring organization in GSoC 2010.

Check our special Summer of Code page for further information on how to contribute to LibreDWG as a SoC student.

Git push access

We want contributors, and we believe that giving them write access to the git repository means we trust their work and we want them in our team. Therefore, we have a slightly liberal write access policy: if you submit two non-trivial patches and they get accepted, you're in. As stated above, we've assigned the copyright to the Free Software Foundation. So, in order to become an official developer, you'll have to fill the following form and mail it to fsf-records@gnu.org and please carbon copy (CC) libredwg-owner@gnu.org:

Please email the following information to fsf-records@gnu.org, and we
will send you the assignment form for your past and future changes.
Please use your full name as the subject line of the message.


[What is the name of the program or package you're contributing to?]
LibreDWG

[Did you copy any files or text written by someone else in these changes?
Even if that material is free software, we need to know about it.]


[Do you have an employer who might have a basis to claim to own
your changes?  Do you attend a school which might make such a claim?]


[For the copyright registration, what country are you a citizen of?]


[What year were you born?]


[Please write your email address here.]


[Please write your snail address here.]

[Which files have you changed so far, and which new files have you written
so far?]

Who uses it?

  • GRASS - DWG import plugin (v.in.redwg)
  • LibreCAD - LibreCAD developers are experimenting with a DWG import filter for their CAD software using LibreDWG.

Talking to us

If you just want to ask a question or give us some ideas, feel free to write to or join the developers' mailing list.

If you just want to be updated about important LibreDWG announcements and releases, join the low traffic announcements mailing list.

Follow the identi.ca group for instant updates.

Follow the news section at Savannah or subscribe to the news atom feed for general announcements for developers, contributors and people who want to keep track of our current work and progress.

Some of the developers also hang out at #libredwg on irc.freenode.net, just drop by and say hello.


Happy Hacking!