I have written an e-book for beginners! lazarus / 8-Other ---------------------------------------------------------------------- nsunny · 2017-12-15 19:51 Hello everyone! Happy Holidays. I have written an e-book on Lazarus. This is for absolute beginners. I have tried to keep it as friendly and short as I could. Has only 10 chapters and should have anyone up and running in no time. Has helpful graphics to make things easier. PDF Download: https://github.com/adnan360/lazarus-beginners- guide/releases/download/v1.0.0/lazarus-beginners-guide.pdf GitHub: https://github.com/adnan360/lazarus-beginners-guide Related Post: http://lazplanet.blogspot.com/2017/12/supercharge-your- beginner-friends-with.html The e-book is licensed CC BY 4.0 so you can remix and release your own versions if you want. Even use in commercial purpose. You can find the source files on github link. I also have a plan to write a longer book in future going into further details. I am not an expert in Lazarus, but I want to do something for this amazing IDE. Have fun sharing! ---------------------------------------------------------------------- BlueIcaro · 2017-12-15 20:56 Great job! Thanks for share it! One sugestion,  I did a fast read, In charpet 9. you talk about sharing your project. You say that you can delete some files. I'm not a lazarus/pascal programmer expert  but I think you can use publish project in the project menu to do the same task. http://wiki.freepascal.org/IDE_Window:_Publish_Project_Package /BlueIcaro ---------------------------------------------------------------------- Handoko · 2017-12-16 02:33 @nsunny Thank you for writing the guide. Wow, I really can see your efforts to make it easy to follow. It has pictures, screenshots and clear instructions. You should consider to write for more different topics. And thank you for the LazPlanet, which I often recommend for beginners. ---------------------------------------------------------------------- ccrause · 2017-12-16 06:09 Well done, an easy read. ---------------------------------------------------------------------- nsunny · 2017-12-16 14:28 Quote from: BlueIcaro on December 15, 2017, 09:56:55 pmOne sugestion,  I did a fast read, In charpet 9. you talk about sharing your project. You say that you can delete some files. I'm not a lazarus/pascal programmer expert  but I think you can use publish project in the project menu to do the same task. http://wiki.freepascal.org/IDE_Window:_Publish_Project_Package /BlueIcaro Thanks for pointing that out. I think last time I tried File - Clean Directory but it did not work for me for some reason (left out some files). I totally missed the Publish project feature. If it works, that would be better and easier option to include. I will surely look into this and if works would put into next edition. ---------------------------------------------------------------------- molly · 2017-12-16 17:24 Quote from: nsunny on December 16, 2017, 03:28:02 pmIf it works, that would be better and easier option to include. I will surely look into this and if works would put into next edition. For sure it works  Been using that since ages and is also the recommended way of 'publishing' your project f.e. in order to attach it to a forum post. In case you add it to your book (thanks for that btw) then make sure to handle the publish directory option carefully. The default directory is a bit awkward. There are some 'macro's that can be used in the directory name. ---------------------------------------------------------------------- nsunny · 2017-12-17 18:43 @molly I have tried the Publish Project option. I just created a new project, hit run, brought up the dialog, selected a new directory, and submitted. From 2 folders and 8 files, it made it 4 files in the target folder: lpi, lpr, frm, pas. I was happy with the result, then promptly found out that the icon vanished! Even not visible on titlebar of my form when I run it. Maybe I would need to read about this feature. Do you have any suggestions if I can fix this somehow, with less change of the default values? ---------------------------------------------------------------------- molly · 2017-12-17 18:54 Aboutth emissing icon. I'm doing this from memory (no lazarus around atm), so please don't shoot me when wrong. Afaik you are able to configure the file extensions that should be published. I take it that the icon file is not considered important enough to publish (by default). The fact is it is not important, as your project will compile perfectly ok without it. Unless of course your aim is to also 'pass along' the icon. ---------------------------------------------------------------------- wp · 2017-12-17 19:05 Yes, add the extension ico to the "include filter". Add also the extension res if you changed anything in "Project options" > "Version info". But be aware: If you plan to upload a project to the forum or bug tracker you should NOT include ico and res because they are not needed to demonstrate an issue and would only blow up the upload size. ---------------------------------------------------------------------- nsunny · 2017-12-17 19:07 Quote from: molly on December 17, 2017, 07:54:16 pmIt is from memory, so please don't shoot me when wrong. No problem. I won't blame you. I just need to know more. I tried to be sure if I am going in the right way. Quote from: molly on December 17, 2017, 07:54:16 pm...I take it that the icon file is not considered important enough to publish (by default). Hmm... I agree, it is a strange default. I think I would need to try for a while. I also did not find any useful documentation on it. Just these: http://wiki.lazarus.freepascal.org/IDE_Window:_Publish_Project_Package http://wiki.freepascal.org/Lazarus_IDE_Tools#Publish_Project These seem not so much helpful for me. I guess I'll have to use trial and error to find out. ---------------------------------------------------------------------- nsunny · 2017-12-17 19:16 Quote from: wp on December 17, 2017, 08:05:15 pmYes, add the extension ico to the "include filter". Add also the extension res if you changed anything in "Project options" > "Version info". But be aware: If you plan to upload a project to the forum or bug tracker you should NOT include ico and res because they are not needed to demonstrate an issue and would only blow up the upload size. Thanks for the info. It seems a bit odd. Bug tracker should not be the only purpose people will use this feature. Shouldn't there be an option to include the ico and res files? Should users type them everytime when Cleaning or Publishing the project? You and I can add them, no problem. But what about newbies? They will have to remember these extensions. This can be even devastating for a normal user. Suppose they ran Clean Project and forgot to add ico and res file extensions. Then they would loose their icon and resource files. It would be better if we had a checkbox (or a button) which included these for us. ---------------------------------------------------------------------- molly · 2017-12-17 19:22 @wp: Thank you ! @nsunny: Yes, you bring up some valid points. The 'usual' way (if one can speak bout something being usual with regards to lazarus) is to have the options for multiple configurations (just like you are to do for example for compiling your project as debug or release). There are so many things with regards to lazarus that requires attention, and quite honestly afaik you are the first person to express your concerns. I don't know if it would be worth a feature request.... ---------------------------------------------------------------------- nsunny · 2017-12-17 19:55 @molly Quote from: molly on December 17, 2017, 08:22:50 pm...The 'usual' way (if one can speak bout something being usual with regards to lazarus) is to have the options for multiple configurations (just like you are to do for example for compiling your project as debug or release). There are so many things with regards to lazarus that requires attention, and quite honestly afaik you are the first person to express your concerns. I don't know if it would be worth a feature request.... Thanks for agreeing. Some changes would be nice for newbies. I also talked about changes in the splash screen and the website (many days ago). Sometimes the community shows less interest in some things. I had wonderful time designing the Lazarus website and got help from the community as well. but never got time to spend or present more positive thoughts for the splash screen myself. But look forward to it one day. I believe with some modern graphics, branding and improvements Lazarus should look a lot better and attract more people towards it. I am always so excited about Lazarus. I want to do so much more. But don't always have the time, unfortunately. I am not used to requesting feature in Lazarus (don't know how to). But if anyone else can make the request for us, that would be awesome. ---------------------------------------------------------------------- BlueIcaro · 2017-12-17 21:01 nsunny you did a great job. I like very much the design, it's cool. Books like that make easy learning. /BlueIcaro ---------------------------------------------------------------------- dbannon · 2017-12-17 22:45 I think this is brilliant, and I thank you on behalf of all the beginners who will become great members of the FPC/Lazarus community !  This is how we can build that community folks ! Hope you don't mind if  make a couple of constructive suggestions ? Firstly, you use the word 'tool' when referring to visual components, I'm not sure thats a good idea. Possibility of confusing your 'tool' with the ones provided as part of FPC/Lazarus. People tend to think of tools as something you use here to help make the software rather than actually part of the software. Secondly, installing. I think it would be a good idea to point people to the newly released install kits that ship 1.8.  The Linux package maintainers can be quite slow in pushing out new versions, especially for people on long term release OS. Another thing you probably have not come across is how hard Mac makes things for non Mac developers. So someone attracted to Lazarus's cross platform nature may find themselves looking at a Mac for the first time. On Mac's, to use the app outside of the IDE you need to make an "application Bundle" (press the button in Project Options) and then run (from memory) ~/MyApp.app/Contents/Mac/MyApp and to move the app elsewhere you need to delete the symlink down in that location and replace it with the actual binary. I'll try and document this process and how to make a distributed dmg file on the wiki when I get some free time. This script does it (but I don't think it would be a good idea to link directly to it) - https://github.com/tomboy-notes/tomboy- ng/blob/master/package/mk_dmg.bash Perhaps all you need do in your book is mention that Mac's need that application bundle to be made and refer people to wiki ? ---------------------------------------------------------------------- nsunny · 2017-12-18 03:25 Quote from: dbannon on December 17, 2017, 11:45:29 pmFirstly, you use the word 'tool' when referring to visual components, I'm not sure thats a good idea. Possibility of confusing your 'tool' with the ones provided as part of FPC/Lazarus. People tend to think of tools as something you use here to help make the software rather than actually part of the software. I was also thinking about it. I think it is ok in the case of the toolbar, but not so much when they are dropped to form. I think I need to find out a new word for this. But this is also true that sometimes teachers find some temporary words to make the students comfortable. This is so that they don't get lost in the new words and jurgons and start thinking its hard and give up. Maybe it is something like that. But I will think about changing it for sure, if I find any replacement. QuoteSecondly, installing. I think it would be a good idea to point people to the newly released install kits that ship 1.8.  The Linux package maintainers can be quite slow in pushing out new versions, especially for people on long term release OS. I think that's great. I don't run Ubuntu for many days. But the last time I checked in a LTS, it was already to 1.4 or something. (I don't remember correctly though.) 1.4 would be ok to newcomers to try the basic things, but 1.0.6 or 9.x.x versions would be a problem to follow. Especially the compile sections in settings are different. I think if the Wiki addresses this issue in some separate section of the Ubuntu page (wiki.lazarus.freepascal.org/Install_on_Ubuntu), it would be much better. Then I can shortly refer to that section if someone has the older version. QuoteAnother thing you probably have not come across is how hard Mac makes things for non Mac developers. So someone attracted to Lazarus's cross platform nature may find themselves looking at a Mac for the first time. On Mac's, to use the app outside of the IDE you need to make an "application Bundle" (press the button in Project Options) and then run (from memory) ~/MyApp.app/Contents/Mac/MyApp and to move the app elsewhere you need to delete the symlink down in that location and replace it with the actual binary. I'll try and document this process and how to make a distributed dmg file on the wiki when I get some free time. This script does it (but I don't think it would be a good idea to link directly to it) - https://github.com/tomboy-notes/tomboy- ng/blob/master/package/mk_dmg.bash Perhaps all you need do in your book is mention that Mac's need that application bundle to be made and refer people to wiki ? I don't have a Mac in my hand and I am not that accustomed to it. I see the wiki is loaded with text (http://wiki.freepascal.org/Installing_Lazarus_on_MacOS_X) and would not be helpful to newcomers. It would be great if you or someone else can provide me some instructions for Mac (preferably short and understandable) then I can include it in the next edition. Or better also, if the Wiki has this short instruction and just link from the book. Thanks for the good points. ---------------------------------------------------------------------- dbannon · 2017-12-18 06:00 Ah nsunny, no ! Quotecan provide me some {INSTALL} instructions for Mac As I noted at the top of the page about installing on Mac, its not hard but it is tedious !  Its not Lazarus/FPC's fault, there are just heaps of other things, XCode, Brew, gdb that have to be installed AND got working and there are lots of steps. And that page is not all, it links to a couple of other, quite detailed sets of instructions. Sorry, thats just how it is. Its a pity. Disclaimer - I wrote much of the new content at the top of that page. ---------------------------------------------------------------------- nsunny · 2017-12-18 19:53 @dbannon Oh my! You are right. I did not know it was that difficult to install on a Mac. I wonder who built the install system on Macs. This is not user friendly! Even linux is easier than Mac! I have installed Lazarus on Arch Linux with just: Code: [Select]sudo pacman -S lazarus lazarus-qtOn Windows I have just double clicked the install file and continued. I have searched on Youtube to see if there is any video showing the process and perhaps if somebody found an easier way. I found this one: https://www.youtube.com/watch?v=QE_IAjkXElg It shows the process. This is easier to follow than the wiki. Maybe I can link to it on my ebook to make things easy to understand. I also learned about why all the steps are necessary on this video: https://www.youtube.com/watch?v=CN0o_qX4A8c EDIT: I guess this is also possible ( for Lazarus 1.8 ): QuoteNo debugger. In Lazarus 1.8 you can choose Run->Run without Debugger or set it up to always run without debugger. OK if you are building code developed elsewhere and certain to build cleanly (yeah, thats likely).source: http://wiki.freepascal.org/Installing_Lazarus_on _MacOS_X#Step_3_install_gdb ---------------------------------------------------------------------- Phil · 2017-12-18 20:29 Quote from: dbannon on December 17, 2017, 11:45:29 pmFirstly, you use the word 'tool' when referring to visual components, I'm not sure thats a good idea. Possibility of confusing your 'tool' with the ones provided as part of FPC/Lazarus. People tend to think of tools as something you use here to help make the software rather than actually part of the software. Right. The term for a visual component is "control". Has been since VCL 1.0. Same with LCL. Same elsewhere, Eg, in Mac Cocoa framework, NSControl is the ancestor class of the visual parts: https://developer.apple.com/documentation/appkit/nscontrol In Delphi and Lazarus, everything on palette descends from TComponent, but visual components descend from TControl. "Tool" is just wrong. Quote from: dbannon on December 17, 2017, 11:45:29 pmAnother thing you probably have not come across is how hard Mac makes things for non Mac developers. So someone attracted to Lazarus's cross platform nature may find themselves looking at a Mac for the first time. On Mac's, to use the app outside of the IDE you need to make an "application Bundle" (press the button in Project Options) and then run (from memory) ~/MyApp.app/Contents/Mac/MyApp and to move the app elsewhere you need to delete the symlink down in that location and replace it with the actual binary. No, the issue is that Lazarus has never been able to create a proper app bundle. No other Mac IDE has this problem. You can avoid this Lazarus bug by starting your Lazarus project as a cross-platform project using this add-in: https://macpgmr.github.io/MacXPlatform/LazXProj.html ---------------------------------------------------------------------- Phil · 2017-12-18 20:33 Quote from: dbannon on December 18, 2017, 07:00:48 amIts not Lazarus/FPC's fault Yes, it is Lazarus/FPC's fault. FPC depends on Xcode's linker, assembler, etc. so Xcode has to be installed first. Developers on Mac will already have Xcode installed, so you're talking about newcomers to Mac or hobbyists who have a Mac if they're surprised by this requirement. But it can be installed in one click from the Mac App Store. The debugger on Mac is lldb. Lazarus still tries to use gdb, which hasn't been part of Xcode for years. My understanding is that some debugger solution for Mac was imminent several years ago, but that effort appears to have stalled: http://lazarus-dev.blogspot.com/2014/05/de-bug-wars-new-hope.html ---------------------------------------------------------------------- nsunny · 2017-12-18 20:49 @Phil Quote from: Phil on December 18, 2017, 09:29:25 pm"Tool" is just wrong. I agree. I have used it as a placement word to make things easier. As a beginner, it is not important to remember exactly which is called which. Concept is more important in this stage. Every other reference will guide him gradually to use the correct word. Also, I have called it Component once (when talking about component toolbar icons) and indicated that it is the real name and said that we're going to ignore the real name: QuoteAt the top there are some tools that you would drop into your form. (Tools are formally called “components”. But let’s forget that for now!) Teachers sometimes call some things like this. He gives temporary names to things or even links stories to make the topic easier for the students, even if the story is not completely relevant. When he understands the whole thing, then the real names become easier to grasp. Can you tell me if this is a good idea? I have no access to Mac so I can't test it. QuoteNo debugger. In Lazarus 1.8 you can choose Run->Run without Debugger or set it up to always run without debugger. OK if you are building code developed elsewhere and certain to build cleanly (yeah, thats likely). ---------------------------------------------------------------------- Phil · 2017-12-18 20:57 Quote from: nsunny on December 18, 2017, 09:49:38 pm@Phil Quote from: Phil on December 18, 2017, 09:29:25 pm"Tool" is just wrong. I agree. I have used it as a placement word to make things easier. As a beginner, it is not important to remember exactly which is called which. Concept is more important in this stage. Every other reference will guide him gradually to use the correct word. Also, I have called it Component once (when talking about component toolbar icons) and indicated that it is the real name and said that we're going to ignore the real name: QuoteAt the top there are some tools that you would drop into your form. (Tools are formally called “components”. But let’s forget that for now!) Teachers sometimes call some things like this. He gives temporary names to things or even links stories to make the topic easier for the students, even if the story is not completely relevant. When he understands the whole thing, then the real names become easier to grasp. But a control is not a tool. Analogy: A paintbrush is a tool, as is Lazarus IDE. The paint that's applied by the tool is more like a control. Quote from: nsunny on December 18, 2017, 09:49:38 pmCan you tell me if this is a good idea? I have no access to Mac so I can't test it. QuoteNo debugger. In Lazarus 1.8 you can choose Run->Run without Debugger or set it up to always run without debugger. OK if you are building code developed elsewhere and certain to build cleanly (yeah, thats likely). If someone can't get gdb installed (or doesn't want to install gdb), that's a reasonable approach to getting started quickly. Note that debugging with the supplied Xcode lldb debugger is easy to do once you're built the app. Just start the app via the debugger from the Terminal command line. Eg, lldb MyProgram.app https://developer.apple.com/library/content/documentation/IDEs/Concept ual/gdb_to_lldb_transition_guide/document/lldb-terminal-workflow- tutorial.html http://lldb.llvm.org/lldb-gdb.html Edit:  Oops, forgot. You can also debug a Laz app with lldb in Xcode: https://macpgmr.github.io/ObjP/ProjectXC.html ---------------------------------------------------------------------- nsunny · 2017-12-18 21:15 QuoteBut a control is not a tool. Analogy: A paintbrush is a tool, as is Lazarus IDE. The paint that's applied by the tool is more like a control.That's a great opinion. I could not find any better word at the moment so I used it. You can suggest a better word. But whatever you suggest, it should be easy for the beginners. There are hundreds of resources out there that are not beginner friendly. They say that when it is on toolbar it is called "Component" and when it is dropped on the form it is a "Control" or an "Object". I think this book should stay out of this to be simple and welcoming to newcomers. Other resources can have the accurate words to guide them later if necessary. QuoteIf someone can't get gdb installed (or doesn't want to install gdb), that's a reasonable approach to getting started quickly.I think this is easier. ---------------------------------------------------------------------- molly · 2017-12-18 21:30 Quote from: nsunny on December 18, 2017, 10:15:35 pmThere are hundreds of resources out there that are not beginner friendly. They say that when it is on toolbar it is called "Component" and when it is dropped on the form it is a "Control" or an "Object". I think this book should stay out of this to be simple and welcoming to newcomers. Fact is that they are all correct  TControl -> TLCLComponent -> TComponent -> TPersistent -> TObject Once you see/understand the inheritance, it is all starting to make sense. I agree that starting with explaining inheritance would not be a good idea for complete programmer newbies. In that regards i also agree that it is sometimes a better choice to use analogies. Just be careful which analogies to use. If you want to avoid confusion then it is usually better to tackle that issue heads on, and explain it correctly and into detail right from the start (the attention span these days is not very long  ). PS: "The watchers always know better than the doers" ---------------------------------------------------------------------- dbannon · 2017-12-18 23:03 QuoteThat's a great opinion. I could not find any better word at the moment so I used it. You can suggest a better word. But whatever you suggest, it should be easy for the beginners.nsunny, I agree its a good idea to simplify in beginner texts but its not a good idea to mislead. A tool is something the developer uses, he/she does not ship a tool with the product. Phil suggested "control", that probably is the best choices. "Tool" is wrong. QuoteI think this {leaving gdb out} is easier.Perhaps. But I do think you should note that a debugger makes a huge difference when someone is struggling to understand how things work, or don't work. Not having a debugger would probably leave a few newcomers feeling they are lost and the IDE is not helping. Choose between short term easier and long there easier ! Davo ---------------------------------------------------------------------- Phil · 2017-12-19 00:24 Quote from: dbannon on December 19, 2017, 12:03:49 amQuoteThat's a great opinion. I could not find any better word at the moment so I used it. You can suggest a better word. But whatever you suggest, it should be easy for the beginners.nsunny, I agree its a good idea to simplify in beginner texts but its not a good idea to mislead. Not sure I would say misleading. I accept that he was trying to simplify the terminology, although I think we do that at our peril. I looked around at other introductions. For example, with Swift Playgrounds, I don't see much discussion of the visual elements, but when they come to the Swift syntax and fundamentals, they don't shy away from using the expected terminology (variables, loops, functions, etc.) - and this is for schoolchildren. https://www.apple.com/swift/playgrounds/?cid=wwa-us-kwbi-ipad&muid=e43 b0535-114a-4679-8f8e- b0b6788b3c88&mtid=2092592t39165&aosid=p238&mnid=IJKwGAqO- dc_mtid_2092592t39165_pcrid_12370304354_ Many programming introductions nowadays are not written tutorials in the traditional sense, but Web-based apps that allow beginners to start working with the language or library without installing anything. Again, the various Swift Sandboxes: https://www.weheartswift.com/swift-sandbox/ https://swift.sandbox.bluemix.net/restricted#/repl Even the qooxdoo JavaScript framework has its own Playground app, which allows you to test not only JS code but visual controls on both desktop and mobile as well, all in the comfort of your browser: http://www.qooxdoo.org/current/playground/ Something like a sandbox or playground for FPC and/or Laz might be interesting. ---------------------------------------------------------------------- nsunny · 2017-12-19 20:35 I think the word "Tool" is easier for beginners. But then again, this is also true: QuoteA tool is something the developer uses, he/she does not ship a tool with the product. QuoteFact is that they are all correct  TControl -> TLCLComponent -> TComponent -> TPersistent -> TObject Thanks for clearing that up. If I can decide on applying the formal terminology, I think "Component" best suits the purpose. The Lazarus interface uses the word "Component" very often. The Ctrl+Alt+P dialog has it, and even the filter on the Object Inspector has it. So it would be easier to remember this through repeatation (as he uses Lazarus more and more). But again, I think we would need to check this with real beginners to see which one they like. Afterall we are writing for them. You guys can ask newcomers in your circle to see which one they like, or which one is easier for them. "Tools", "Components" or any other word. I have listed your valuable feedbacks. I would work on them in the future version. Please let me know what you find talking with newcomers. ---------------------------------------------------------------------- molly · 2017-12-19 21:42 I would personally go with the word component. I use it in my teachings as well. The word component is technically correct and comparable with the word ingredient, a building block that when put together with more of them can become an end-product. Just like a house that's build with an amount of individual bricks. Using the word component has another advantage as you are able to specifically mention any of its ancestors without punishment or sounding strange. Another advantage is that (later on) you are able to specify the difference between visual and non-visual components. That way it also doesn't become awkward when you tell/describe to people that a control is a visual component. 2 cents ---------------------------------------------------------------------- Zath · 2018-01-25 22:47 Nice work. Two minor things. One:-Component gets my vote over tool. Two:- The font you use in the emphasised code makes parentheses look similar to square brackets. A newbie "could" mistake one for the other. ---------------------------------------------------------------------- Oscar Vazquez · 2021-09-02 18:36 Can I translate the Electronic Book for the Spanish language ???? With your permission ??? ---------------------------------------------------------------------- ccrause · 2021-09-02 18:50 Quote from: Oscar Vazquez on September 02, 2021, 08:36:36 pmCan I translate the Electronic Book for the Spanish language ???? With your permission ??? The author seems to encourage this based on the document's license[url]: QuoteLicense This project is licensed under Creative Commons Attribution 4.0 International (CC BY) Any remix of the book is encouraged.