Optional instructions for using a real MeeGo device

Optional instructions for using a real MeeGo device

If you have a real MeeGo device available, it’s also possible to run and debug your application on it using Qt Creator. 

Prepare the device

The device requires some configuration and extra packages before you can deploy from Qt Creator to it. Install them from the command line as follows: 

1. Deployment from Qt Creator to a real device uses SSH for file copying, so you need to install OpenSSH server on the netbook with:

   sudo zypper install openssh-server

   To start it manually (you’ll need to do this just after you’ve installed it, otherwise it won’t be available until you reboot): 

   sudo /etc/init.d/sshd start

   To add it to the init sequence so it starts at boot time: 

   sudo chkconfig --add sshd

2. If you want to debug applications remotely, you need to install gdbserver on the netbook:

   sudo zypper install gdb-gdbserver

Run the application on the device

In Qt Creator (still running from the chroot): 

1. With a project selected, click on the Projects icon to show the project configuration tabs.
2. Select the Run Settings tab.
3. Click on the Add drop-down and select testapp on MeeGo device (testapp will be set to the name you gave your project).
4. Click on the Manage device configurations link to display the MeeGo Device Configurations dialog.
5. Click on the Add button (top-right) and complete the fields so they resemble the screenshot below:
   
   You’ll need to set Host Name to the IP address or domain name of the netbook, and enter the User Name and Password you used when you set up the netbook. The other options can be left at their defaults.
6. Click on the Test button to check the connection. If it’s configured correctly, you should see a message like the one in the screenshot above (“Device configuration successful”).
7. Click on OK to save your changes. This returns you to the Run Settings tab.
8. Select the new MeeGo netbook option from the Device Configuration drop-down.

Once you’ve completed this, you should be able to deploy and run the application on the netbook: 

1. At the bottom-left of the Qt Creator window is a panel for selecting the build and run environments:
   
   Click on the computer monitor icon, then use the arrows to select testapp on MeeGo device from the Run drop-down. The Build drop-down can be left at Debug.
2. Click on the green arrow (the normal run arrow) to deploy the application and run it. This copies the application binary to the home folder of the user you specified in the SSH settings and runs it.
   If you can’t see the application, it may be because it hasn’t been given focus. You can use the zones icon in the toolbar to show the running application and select it.

Here’s an example of what the application looks like running on a netbook: 

 

Debug the application on the device

This works almost the same on a remote device as it does inside the Simulator. 

1. Configure the remote device as explained above.
2. In Qt Creator, click on the Target settings (bottom left with a monitor icon). Ensure you have Build set to Debug and Run set to testapp on MeeGo device (the remote device).
3. Click on the green arrow overlaid with a bug to start the application remotely in debug mode.

If you used the same code as above, try clicking on the Click me button in the application (running on the netbook). The application should pause at the breakpoint; and in Qt Creator, the message variable should then be visible in the Locals and Watchers tab, set to “I have been well and truly clicked”. (No screenshot this time, as Qt Creator looks the same as it does for local debugging.) 

Retrieved from “ http://wiki.meego.com/Hello_World_-_Linux%E4%B8%8A%E7%9A%84_MeeGo_x86_%E5%BC%80%E5%8F%91“

• (3)Packaging MeeGo applications

  To distribute an application to a MeeGo device, it should be packaged using the RPM format. (It is possible to manually copy binaries to a device and get them to run, but this is not recommended, as there is no way to specify dependencies.)An RPM file is a binary file consisting of: 

  • A signature to verify the origin and integrity of the package
  • Metadata (name, version, architecture, authors etc.)
  • An archive of files to be installed on the destination filesystem (e.g. executables, images, documentation)

  This Packaging/Tutorial will give you a whole story to create a rpm package from a qt project. 

  References for packaging : 

  • Build System
  • Packaging
  • Packaging/Guidelines
  • Packaging/Deb conversion example

•  

  MeeGo application developer cookbook

  • Porting Linux applications to MeeGo

  •  See MeeGo Netbook and GTK 

  MeeGo platform developer tutorials

  • Creating MeeGo disk images

    See:

    • ARM/Creating_ARM_image_using_MeeGo_Image_Creator
    • Image Creation
    • Image Creation For Beginners

   

    

   

  Developer documentation guidelines

  • SDK documentation guidelines 

  A set of documentation principles describing the documentation process and the different licenses for different documents.

  Contents [hide]   1.1 Picking up documentation tasks 1 Developer Guide process 2 Content categorization 3 Licensing

   

  Developer Guide process

  The intention behind the Developer Guide is to sign-post the most-accurate information available to MeeGo developers. As such, it should not be added to in an ad hoc fashion or subjected to massive restructurings without community involvement. Usual MeeGo SDK community channels can be used to discuss changes. 

  If you notice an improvement which could be made to the Developer Guide, you have a few options: 

  • Fix it yourself (if it’s already in the guide); let the meego-sdk mailing list know if it’s anything significant (e.g. you removed or added a large chunk of text; fixing typos is OK and you don’t need to tell anyone etc.)
  • Write a new page yourself and log a request to have it added to the Developer Guide; include the title of the page in the title of the bug
  • Log an enhancement request for a page to be added to the Developer Guide if you can’t or won’t write it yourself; be as specific as you can about the content you expect to see in it
  • Log a bug if you spot a problem on a page (something wrong, something missing) and can’t or won’t fix it yourself; requests to remove a page, move a page out of the guide etc. can also be made this way

  Bugs and enhancement requests are logged on http://bugs.meego.com/, inside the Documentation product, SDK docs component. 

  • Create a request for documentation
  • Current open SDK docs bugs

  Documentation issues should also be attached to the appropriate version of the Developer Guide (corresponding to MeeGo versions): check the version of the Developer Guide you’re viewing and select the appropriate version when making your request. 

   

  Picking up documentation tasks

  Documentation bugs can be taken on by any MeeGo SDK community member. Please review the SDK Tutorial Content page when authoring new content. 

  Bugs are closed at the discretion of the MeeGo SDK community; for example: 

  • A request for a new page can be closed when a page is in place which satisifies the requirements specified in the bug.
  • A request to include a new page in the Developer Guide can be closed when the page is linked from the Developer Guide table of contents.

   

  Content categorization

  See Developer guide content organisation for some suggestions about how to categorise developer guide pages. 

   

  Licensing

  Creative Commons Attribution 3.0 is the licence for the wiki; documentation uses the same licence 

  Retrieved from “ http://wiki.meego.com/SDK_documentation_guidelines“

  • Technical documentation style guide

  • Some tips for writing MeeGo technical documentation. These are based on my personal experience (as a technical writer).The intended audience is anyone wanting to write documentation covering how to develop for MeeGo, e.g. someone writing tutorials or recipes for application developers or platform developers, someone writing a course on MeeGo development. It does not cover: 
    • The right structure for documentation: it’s more about general principles of technical writing
    • Wiki mark-up to use: it doesn’t cover whether to use bold or italics for user interface element names, when to use fixed-width fonts, or any of that stuff

    Note that this is a work in progress, so should improve over time.

    Contents [hide] 1 Start from a known state 2 Tell a story 3 Write conversationally and informally 4 Use task-based structures 5 Explain too much, rather than too little 6 Compare the new with the familiar 7 Provide useful, relevant, meaningful examples 8 Leave a gap between drafts

    Start from a known state

    You should explain why the document exists: 

    • What it will show you to do (build a PDF viewer, understand how DBus works)
    • The intended audience (beginner, C programmer, web programmer)
      See Audience for MeeGo developer documentation for some examples of the range of MeeGo audiences
    • The vertical it’s applicable for (will it only work for netbooks?)

    Also explain any assumptions you’re making about the reader and their context. For example: 

    • A “getting started” tutorial should start from a clean install of an operating system.
    • A tutorial about “advanced widget use” might build from a state reached in a previous tutorial. But you need to make that explicit: say, “You should do tutorial X before you start this tutorial”.
    • A programming tutorial should either tell the reader what they need to install, or tell them where to find that out, or tell them they should go and work it out for themselves.

    You can be explicit about where a MeeGo SDK guide belongs by categorising it: I put some suggestions about how to do this in Developer guide content organisation. 

    Tell a story

    Start with small pieces and join them into a significant whole: you’re taking the reader on a journey where they’ll hopefully be a different (preferably better) person by the end. 

    Make sure there’s a progression (from them knowing “little or nothing” to them knowing “something”). 

    Only add a small amount at each step, and make sure what you add at each step is a coherent unit: for example, implement a single feature or explain a single concept. (Though working out how big a “unit” should be is tricky in itself.) 

    You could show a screenshot of the finished application and then say “here’s how we got here”. But don’t start with a big pile of code and try to pick it apart and explain it. That’s difficult for someone to grasp. If you’re writing about building a full application, add the features in a logical order the way a developer might do it, e.g. 

    1. Set up the project
    2. Create the basic skeleton of the application
    3. Add some read-only/inactive widgets
    4. Add behaviour to the widgets but stub out interactions with other parts of the environment
    5. Add interactions with the real environment (e.g. fetch data from the network, talk to device APIs)

    Make sure there is a reason for adding each new feature. Adding spurious, unrealistic, disjointed (but maybe cool) features doesn’t make a good story. 

    You could also use “characters” and put them in scenarios which mirror development in the real world. For example: 

    • A developer is being asked by a customer to add new features to an application.
    • A tester and developer are working together on testing an application.
    • A developer is writing an application for his girlfriend.

    The O’Reilly Head First books are a good example of how to do this well 

    Write conversationally and informally

    While writing, imagine you’re explaining to a peer, colleague, family member or friend (depending on the type of audience you’re writing for). This makes your writing more natural and help you get the flow right: it’s easier to track a conversation in your head than it is to track an abstract explanation. 

    Use “we” and “you”; address the reader directly. Compare the following two pieces of text and see which one reads better: 

    The button widget can be added to a layout using the add_actor method.

    You can add a button widget to a layout using the add_actor method.

    (I’d argue the second reads better.) 

    Use task-based structures

    Explain concepts by getting the reader to carry out a task related to them. Rather than explaining about something in abstract, show the reader what “impact” completing that task will have on them: what effect it has on the application, or on their programming skill, or on the world around them (more generally). 

    For example: 

    • “Configuring the application” rather than “Application configuration”
    • “Writing a depth-first parser” rather than “Depth-first parser construction”
    • “Adding a label widget” rather than “Label widgets”

    This means someone knows what they’re going to achieve by the end of the section, and has an idea of the scope of the information in that section. 

    Explain too much, rather than too little

    Try to make the right assumptions about the reader, what they know, and the context they’re working in. Having a fictional conversation with someone real helps with this, as you can use what you know about that person to decide what to explain. For example: 

    • If I’m writing a beginner programming tutorial, I imagine I’m talking to one of my friends or family, who understands computers (they know what a menu is, how to select things, understand OK and Cancel buttons), but not so much about programming.
    • If I’m writing about an advanced programming topic, I imagine I’m talking to one of my co-workers. I have a decent idea of their field of reference: they’ll know what the Model View Controller pattern is, understand what a method signature is, be familiar with how network protocols work. At the same time, I try to be aware of what I know which they might not, e.g. “I’ve probably done more web programming than they have, so they may not be so familiar with CSS and HTML syntax”.

    Each time you feel the need to explain something, decide whether that person would already know it. If you’re not sure, explain it. 

    Compare the new with the familiar

    This relates to the previous section: if you’re explaining something new, compare it to something the reader might already know about. Some of the time, if it’s new to you, this can help you understand it, too. 

    As an example, a few months back I helped write a page about DBus. There was a section about signals, but I wasn’t really getting how to use them, and felt this would hinder other people understanding it. So I tried to find an explanation of signals which related to the real world, and came up with this: 

    Signals provide a way for objects to notify other objects about events which happen to them: for example, a Door interface might provide a signal to other objects when it is opened, perhaps called door-opened. (A nearby Doorman object might listen out for door-opened signals, so it knows when people come into the building.)

    Provide useful, relevant, meaningful examples

    Examples should be: 

    • Self-contained (as far as possible): in the case of code examples, you should be able to compile it without needing loads of tools, or use them straight away inside an IDE like Qt Creator. If this isn’t possible, they should include an INSTALL file (or at least README comments) explaining how to build them, distributed with the code (see above).
    • Meaningful: they should provide a solution for some possible issue. For example, if you’re explaining how to use widgets, write an application which demonstrates how to use them in context, e.g. an address book.

    Specifically, code examples should be: 

    • Included in the MeeGo code examples repository/wiki (once we’ve decided on the best format for this). This makes it easier for other people to get at them, fix them, extend and improve them.
    • Available under a liberal open source licence. I suggest BSD.

    Some open problems: 

    • How to include source code in guides. I tend to cut and paste as I go, but maybe there’s a better way.

    Also try to stay focused on the topic. This sounds obvious, but it’s sometimes difficult to resist “showing off”. Just because the history of compilers is very interesting, it doesn’t mean you should cover it in a tutorial about writing desktop applications. 

    Leave a gap between drafts

    Write a first draft, then leave it alone for a few hours (preferably 24). 

    Then go back to it and read it over from start to finish, correcting as you go. Because you’ve had a break from what you’ve written, you’ll be able to look more objectively at it, and be able to spot errors or places where the “flow” isn’t right. 

    Don’t be afraid to restructure. Look for sections you can reduce in size or remove. 

    Retrieved from “ http://wiki.meego.com/Technical_documentation_style_guide“